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Preface 


The introduction of OS/2 provides users of PC’s and PS/2’s with a 
DOS-like environment where they can actually perform multitasking and 
break through the barrier of 640K imposed by DOS. OS/2 also provides a 
friendly ‘‘point-and-shoot” user interface featuring mouse interaction, 
menus and device-independent graphics. 

This sort of operating system provides an ideal platform for scientific 
programs, where data are often large arrays, and where slow data acquisi- 
tion and processing should not lock a system up so that it can’t be used for 
other tasks simultaneously. Thus, the thrust of this book is a series of expla- 
nations and examples of the parts of OS/2 that are most significant in the 
display, plotting, and acquisition of scientific data using interface cards. 

In this book, we begin by showing how to write programs in C, and then 
explain how to write programs for the Presentation Manager so that you can 
get the most out of your system. Throughout, I have tried to include copious 
comments in every program listing so that you can read the comments for a 
quicker understanding of the intent of each program. 

A number of people have made significant contributions to my under- 
standing of OS/2 and the Presentation Manager and I would particularly 
like to acknowledge the help of Gennaro Cuomo, Jason Crawford, and 
Bryan Lewis of the Workstation Projects group at IBM Yorktown, 
Wolfgang Segmuller of the NSF-Net group, Rudy Dobransky in Lab Auto- 
mation, Kaushal Amin from IBM Atlanta, Richard Redpath and Keith 
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Purcell at IBM in Cary, N.C., and David Reich and Marty Klos from IBM 
Boca Raton. 

I particularly wish to acknowledge the clear explanations of device driver 
design that I received from Oleg Vishnepolsky at IBM Research. Much of 
the approach I| describe here is derived from his explanation, and much of 
my first device driver was based on the model of a program he provided to 
me. 

The clever method of linking a small amount of assembly code with a 
small model C program to produce a device driver was outlined to me by 
Dennis Rowe of IBM Boulder, who in turn has acknowledged help from 
Tom Rechtshaffen at IBM Yorktown. I also want to thank Marty Klos of 
IBM Boca Raton for explaining the details of DMA device drivers. 

I also would like to acknowledge helpful comments on my manuscript 
from Frank Novak, David Bolen, Jean-Christophe Simon, Joe Hellerstein 
and Soren Peter Nielsen. Finally, I want to thank Beth McAuliffe and Joan 
Dunkin of the Yorktown text processing group for assistance in preparation 
of the camera ready copy. 

James W. Cooper 
April, 1990 
Yorktown Heights, New York 


€ 


©8080 OOOHOOOOOOOOOHOOOHO8OOOOOCOEEO SC 


e¢ 


SEAT TTT ETE 


Trademarks 


OS/2™, C/2™, Personal System/2™ and Proprinter™ are trademarks of 
International Business Machines Corporation. Personal Computer AT® is 
a registered trademark of International Business Machines Corporation. 
HP™ is a trademark of the Hewlett-Packard Corporation. CodeView® is a 
registered trademark of the Microsoft Corporation. Turbo™ C is a trade- 
mark of Borland International. 


XXI 


BAA TTT 


Writing Scientific 
Programs Under the 
OS/2 Presentation 
Manager 


}@0GdOOO0OGO9HOHOGOOGOHOHOOGOSOHOOOGONOD 


1 Protected Mode Programs 


OS/2 provides you with the ability to use and write programs using the Pro- 
tected Mode of the 80286 and 80386 microprocessors. This means that you 
are free from the 640K barrier imposed by DOS and the Real Mode of the 
8086 series of microprocessors, and can write programs that address and use 
up to 16 megabytes of memory, even if your machine does not actually 
contain this much physical memory. 

More important the Protected Mode actually protects your program 
from accidentally accessing memory that belongs to some other program or 
even changing program code when you really meant to change program 
data. Because of this protection it is possible to write rather complex multi- 
tasking operating systems and assure the user that one task will not interfere 
with another task because of errors in programming or use. If such an error 
occurs, it is trapped by the microprocessor as an exception and usually dealt 
with by the operating system. OS/2 therefore provides you with the ability 
to perform multitasking on your personal computer. 


2 PROTECTED MODE PROGRAMS 


MULTITASKING 


OS/2 defines two types of multitasking: multiple processes and multiple 
threads. 

Processes refer to separate programs that are running simultaneously in 
your computer, each receiving some slice of time. From the user’s point of 
view, he must initiate each independent process by starting a program or 
running a program that starts other programs. Processes may share devices, 
files, or even memory, but can only communicate through semaphores: 
memory locations that can be set or cleared. 

Threads are independent routines within a single program or process that 
run simultaneously. They are able to share data and open files. They are 
started and terminated within a single program, and are used to execute 
time-consuming background activities. For example, you might spin off a 
thread if a long computation is about to commence or if some plotting or 
printing task will take a long time to execute because the printing device is 
relatively slow. In general, threads are used to keep the main program 
“active” to the user, so that he doesn’t have to wait for a job to complete. 

OS/2 also has the ability to run multiple sessions. Each session can have 
its own command prompt and/or screen window. If you start more than one 
OS/2 full screen session, each will have its own full screen and each can run 
its own programs, which can each start several processes and threads. If you 
start OS/2 windowed sessions, they all appear on the Presentation Manager 
(PM) windowed screen at once. There is only one PM screen, but each 
window can represent a session containing one or more processes, or can rep- 
resent part of a process or thread. 


OS/2 PROGRAMMING STYLE 


When you write OS/2 programs, you write them rather differently than 
you would DOS programs, because in a multitasking system you cannot be 
sure whether someone else is also using some of the system’s resources such 
as the screen, disk files, or special-purpose cards. Therefore, in OS/2 you 
cannot: 


1. Write to screen memory. 
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TOOLS NEEDED TO WRITE OS/2 PRESENTATION MANAGER PROGRAMS So 


2. Write to I/O ports using IN and OUT instructions. 
3. Make references to physical memory locations. 
4. Write terminate and stay resident programs of the usual sort. 


Instead, you must execute these functions through OS/2 calls. 


PROTECTION RINGS 


OS/2 1.2 is designed to work on the 80286 microprocessor operating in pro- 
tected mode. The 80386 and 80486 processors run more rapidly than the 
80286 but under OS/2 they operate in 80286 mode rather than in the more 
sophisticated memory modes provided by the 80386. 

The 80286 processor defines four rings of protection, each with 
increasing privilege: 


Ring 3 User programs 

Ring 2 I/O Privileges 

Ring | Not used by OS/2 

Ring 0 Kernel code and device drivers: 


interrupt handling 

Most programs that you write will run at ring 3, with no privileges. If 
you want to write a program that can access I/O ports and execute IN and 
OUT instructions, you must write it to run at ring 2. This is done through a 
special IOPL segment and is discussed later. 

If you wish to control a device and set and acknowledge interrupts, this 
must be done at ring 0. The only kind of program that you can write to run 
at ring 0 is a device driver. Device drivers are programs loaded when the 
system is booted, and are always resident to handle device requests. It is 
through these device drivers that we will see how to control data acquisition 
boards. 


TOOLS NEEDED TO WRITE OS/2 PRESENTATION 
MANAGER PROGRAMS 


To write programs in this operating system, you will need a good 
programmer’s text editor, such as the one provided with OS/2 or any of a 


4 PROTECTED MODE PROGRAMS 


number of commercial editors, a C compiler such as IBM C/2 1.1 or Micro- 
soft C 5.1 that will produce protected mode code, and the OS/2 1.2 
Programmer’s Toolkit. In addition to the manuals provided with the Toolkit, 
you should also have the set of OS/2 1.2 Technical Reference manuals. 
Finally, if you are going to write any device drivers, which require some 
assembly language programming, you will need an assembler that can 
produce protected mode code, such as IBM Assembler/2 or Microsoft’s 
MASM 5.1. Additional vendors are planning to provide equivalent assem- 
blers and compilers as this book is being written. 


ON LINE HELP 


The syntax of all of the OS/2 PM functions is available on line when you 
load the OS/2 1.2 toolkit disks. The manual can be selected as an OS/2 
program, and you can look up the syntax of any OS/2 programming call on 
line. This is somewhat easier than carrying around all of the OS/2 manuals 
needed for programming. 
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2 A Briet Introduction to the 
C Language 


The C language was developed at Bell Laboratories for research use and is 
characterized by a number of features that make it ideal for scientific use. 
In particular, all floating point calculations are automatically carried out in 
double precision. Because of the early slow teletypewriter terminals, C also 
has a penchant for terseness that does not make it easy for the beginner to 
read some C code. In the examples here, we will try to help the reader new 
to C overcome these problems by carefully commenting our code and trying 
to make it as readable as possible. 

This chapter is not a complete tutorial on the C language, but only an 
outline of its high points. If you need to learn the entire language, there are 
a number of excellent texts available. 


ADVANTAGES OF C 


Structure 


One of the great advantages of the C language is that it gives the pro- 
grammer the ability to write structured programs. In particular, you can 
write loops that have clear entry and exit conditions and can write functions 
whose arguments are always checked for correctness. 


6 A BRIEF INTRODUCTION TO THE C LANGUAGE 


Bit Manipulations 


C provides functions for setting and clearing bits and rotating them in 
words, which is a particularly useful concept for setting and clearing regis- 
ters on add-in data acquisition and control cards in your PC. 


Compactness 


C is actually a fairly simple language: a number of the features that have 
been embedded in other computer languages are relegated to library rou- 
tines in C, making the base language quite compact and easy to learn. 


THE C COMPILER 


A large number of compilers have been written for the C language, that 
compile code for virtually any computer system you can name. In this text, 
we will be considering compilers that can produce protected mode code for 
the 80286 and 80386 microprocessors and interact with OS/2. As of this 
writing, two compilers that fill these requirements are IBM C/2 1.1 and 
Microsoft C 5.1. Others will no doubt become available. 

The C compilers are programs that translate the source code written with 
the help of a text editor program and into code for the specific computer on 
which you wish to run your program. The compilers generally produce 
object modules that typically have the .OBJ extension to their filename. 
This object module is linked with standard library routines using a linker 
program to produce an executable code file, having the .EXE extension. 

There are a few compilers available now that have an integrated editing 
and compiling environment, in which you can type in your program, check it 
for errors, compile it, and run it without ever leaving the compiler’s editing 
screen environment. At the moment these compilers, which include 
Microsoft’s Quick-C and Borland’s Turbo-C, do not work in the OS/2 envi- 
ronment, and in particular do not produce code that will run with the OS/2 
Presentation Manager. However, you should look for such products to 
appear. 
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DATA TYPES IN C 


C allows you to manipulate data as various types that are handled and 
checked for consistency by the C compiler. The data types that C handles 


are 


int 


char 


long 


float 


double 


The integer data type. In PCs, this is generally a 16-bit 
integer, but this will certainly vary with the computer’s 
architecture. 


The basic character type. In some machines, this may be 
the same as an integer, and in others it may be an 8-bit 
byte. In all cases, the char type is automatically con- 
verted to an integer where needed during calculation 
without warning the user of this conversion. 


A long integer. In PCs this is a 32-bit integer. 


This is the shortest floating point representation in your 
computer. In the PC, this is a 32-bit number in IEEE 
standard floating point format. A floating point number 
allows you to represent scientific data from about 
1.0E-38 to 1.0E38, where the “E” means that the 
number is multiplied by 10 (not e) raised to that power. 


The double precision floating point representation for 
that computer. It allows you to represent numbers to 
greater precision and, usually, to higher dynamic range 
as well. In the PC environment, double precision allows 
variables from -1.797E308 to -4.94E-324 and 4.94E-324 
to 1.797E308. 


NUMBERS IN C 


All numbers without a decimal point in C programs are treated as integers 
and all numbers with a decimal point are considered to be double precision 
floating point. If you want to represent base-16 (hexadecimal) or base-8 
(octal) numbers you precede the number with ’Ox’ for hexadecimal and just 
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0’ for octal. If you want to specify that an integral value is to be stored as a 
long integer, you must follow it with an “L.” 


015 /*octal 15 or 13 decimal*/ 
Ox15 /*hex 15 or 21 decimal “*/ 
152L /*long integer 152 ay 


WRITING A SIMPLE C PROGRAM 


For our first C program, let us write a program to add together two floating 
point numbers and print out the result. Initially, we won’t bother to read the 
numbers in, but instead will simply use values stored in the program. 

J CORED ED ESE EAE ADD2 PALI BIN AS INTRANET TS IN TUES ETN IN TON OATES EYER BOY PITS 


PS a a Ne 
ANON INNINGS J 


/** A C program to print out the sum of two numbers 


#include <stdio.h> /* contains definitions of printf */ 
j® PA ene RN ey Sean FOTN cd ie a eae eee NMOL A ED IN SOR AU SIT GENTE TT a SEN ESD OT REE Se I RTE MAR * / 
void main() /* main has no return value mf 
{ /* beginning of routine ar 
double a, b, ¢c; /* declare the variables used a | 
a= 2.3; /* assign values to the variables “/ 

b = 4.5; 
c=atb; /* add them together a 
/* print out the result * / 


printf ("The sum is %f \a y €}s 


} /* end of the program | et 


Observations on the ADD2 Program 


There are a number of simple observations we can make about this simple 
program that hold for all C programs. 


1. Comments begin with a /* and end with a */. Comments in this 
program are all less than a line long, but may, in fact, be many lines 
long. 
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2. The #include statement describes a file that is to be read in and used as 
if it were part of the program at this point. The file “stdio.h” contains 
function definitions for standard input and output routines, which in this 
case include the printf statement used in the program. IBM C/2 and 
Microsoft C 5.1 require these include files to describe the number and 
types of variables that may be put in any functions called by your 
program. 


3. The main routine of any C program is always called main(). This is 
where the program starts, regardless of how many routines the program 
contains. 


4. The actual program code begins with a left brace “{” and ends with a 
right brace *}.” 


5. Every statement ends with a semicolon (;). Complex mathematical 
expressions or any other kind of statement may run on for several lines 
if necessary. The statement only stops when the semicolon is found. 


6. All variable names must be declared in advance by name and type. In 
this program, the three variables are all of type double. 


7. The equals sign is used to assign values to variables. Thus 
a = 4.3; 
means “put the value 4.3 in the location where the variable a is stored.” 


8. You can print out results using the printf statement. This statement con- 
sists of a format string and a list of variables. 


9. The backslash character “\” in C has a special meaning. In the printf 
statement, it is used to represent the non-printing character that causes 
a new line to start. This is written as “\n.” 


Strings and Characters in C 


A single character that is used as a constant char is enclosed in single 
quotes: 
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char letter; /* “letter” is of type char */ 
letter = ‘a’: /* assign it the value oy 
/* of the character a i 


A series of characters, however, becomes a quoted string and is enclosed in 
double quotes: 


printf(''hello there’); 


A string is simply an array of characters terminated with a NULL byte. It 
is this NULL byte that determines the length of the string. 

There are a series of special non-printing characters that are represented 
by preceding them with a backslash. The backslash itself is printed by pre- 
ceding it with a backslash: 


\n New line character (carriage return) 

\t Tab character 

\b Backspace 

\0 The null character (usually a zero byte). 
ta Double quote 

V Single quote 

\\ Backslash 

ARRAYS IN C 


In C, all arrays start at an index of 0 and have a final index one less than the 
array’s dimensions. You can declare an array of values in C by simply 
enclosing the number of elements in the array in brackets following the vari- 
able name: 


float freq[500]; /*array of 500 values*/ 
In this case the first element is 
freq[0] 


and the last element 
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freq[ 499]. 


Two-dimensional arrays are represented as arrays of arrays as follows: 


float xmatrix[100][100]; /* 100 x 100 matrix */ 


Elements in these arrays are stored by rows, and the rightmost subscript 
varies the fastest. As we will see later, this somewhat awkward construction 
is seldom used because of the common use of pointers in C. 


CHARACTERS AND STRINGS IN C 


An individual character variable of type char is generally one byte long in C. 
A string of characters is simply an array of characters. 


char name[ 80]; /*80-character string”/ 


However, unlike some other languages, C does not allow you to operate 
directly on strings and assign them to variables. Thus, to copy a string into a 
string variable, you use the common string library function strepy. 


strcpy(name, ‘Anastasia’ ); 


VARIABLE NAMES IN C 


Variable names in C can consist of letters, numbers, and the underscore 
character. They can be uppercase or lowercase or a mixture of cases. Unlike 
most other languages, the case of the characters is significant! Thus the var- 
lables 


Temperature = TEMPERATURE + temperature; 


are all different! There are no real restrictions on the length of variable 
names, but various compilers may restrict the number of characters they 
actually compare to see if two names are identical. In the case of IBM C/2 
and Microsoft C, only 31 characters are significant. 

You can use the case sensitivity and the underscore to improve the read- 
ability of variable names. Some examples include 
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Sum0fPairs 
sum Of pairs 
WinMessageBox 


ARITHMETIC OPERATIONS 


In C, you can perform the usual arithmetic operations on variables and con- 
stants using the usual operators. 


+ addition 

- subtraction 

. multiplication 

i division 

% modulo (remainder after integer division) 
C also has a number of bit operators for performing operations on words: 
>> shift right 

<< __ shift left 

& bit AND - 

| bit OR 

= bit XOR 

ms ones complement 


Note that there is no exponentiation operator. You can call library routines 
for these less common functions. 


The Bit Operations 


You can AND, OR, or XOR together two computer words using the above 
operators. Remember that AND means that a bit is | if both of the input 
bits are ones, and OR means that a bit is 1 if either of the input bits is a one. 
The XOR operation turns on the resulting bits if the two input bits are dif- 
ferent. 
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THE #DEFINE DECLARATION 


C allows you to define a symbolic name for any expression. At the most 
basic level this allows you to make use of named constants that can be 
changed by changing only their definition. 


#define Pl 3.1416 


ye2 * Pl’ rs /*circumference’/ 


Note that the use of the symbol PI actually improves the readability of the 
expression and makes it clear what the constant means. By convention, C 
programmers usually make the names of constants all uppercase letters. 

The #define declaration is actually a directive to a C preprocessor 
program that simply scans the code and substitutes the second expression for 
the first. Thus, you are not limited to numerical values, but can in fact sub- 
stitute whole expressions for particular symbols. 

Note that the #define directive does not end with a semicolon, since it 1s 
not a statement. If you put a semicolon on the line with a #define directive it 
becomes part of the expression that is to be substituted. 


THE PRINTF FUNCTION 


In our first C program, ADD2, we introduced the printf function, which 
consists of a format string and a list of variables. This format string is quite 
powerful and versatile: we will only summarize the more common features 
here: 


char formatstring[nn]; 


printf('‘quotedstring , varl, var2, ...,var_n); 
{* OR = | 
printf( formatstring, varl, var2, ...,var_n); 


The format string can contain 


e text to be printed out 
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e control characters as part of the text 
e format specifiers for variables 


All of the format specifiers start with a % sign. The most common of these 
are 


%f floating point value 
%d integer value 

%ec character 

%s character string 


You can specify a desired field width in these specifiers, by preceding the 
format character with a number: 


Od /* 6 digit integer 
4205 /* 20-character string 


and can add a precision field for floating point numbers: 
%48.2f /* width of 8, 2 decimal places */ 


There is no distinction between floating point and double precision numbers 
because all such operations are carried out in double precision. 


float a; /* define types “/ 


int 43 


a 4.26; 
j= 12; 


printf(''The %dth value is %10.4f ‘it ole 22s 


will print out 


The 12th value is 4.2600 
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The sprintf Function 


The sprintf function performs exactly the same operations as the printf func- 
tion, except that the characters are written into the character array (or 
string) you specify. The function 


char buf[80]; 
float sum; 


sprintf(buf, ''The sum is %8.2f'', sum); 


‘ 


writes the string “The sum is ” followed by the current value of sum into the 
string buf. 

Within the OS/2 Presentation Manager, we never use the printf func- 
tion, but often will write to a text buffer using sprintf and then call a func- 
tion to display the result. 


MAKING DECISIONS IN C 


The if-else statement is the most common way to make decisions in C. 


if (KelvinTemp >= 273.16) 
printf(''Water is liquid \n'); 
else 
printf(''Water is solid \n'); 


This statement says that if the condition in the parentheses is true, execute 
the first statement, and if the condition is false, execute the second state- 
ment. It is also possible to write if statements without else clauses: 


if (Denom <= 1.0e-30) 
printf(''Can't divide by 0! \n''); 


There is, of course, no requirement that the statements under the if and else 
be indented, but it makes reading them somewhat easier. 
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BLOCKS OF STATEMENTS INC 


The C language is considerably more powerful than might be indicated by 
the above simple example. You can write entire blocks of statements that 
are to be executed when a condition is true or false. These blocks are 
enclosed in the same braces used to begin and end the C program: 


r= b™b - 4,0 * a * c; /* value to take root of */ 


if (r >= 0 ) J" if 20 calc. the roots *7 
f 
x1 = (-b + sart(r}37(2.0 * a); 
e2 = (=b = sqrt(rji/(.0 * a): 
orintf( The roots are: %F and YF \ns ¥1s K2)3 
} 


else 


/“or print error message “/ 
printf(''The roots are imaginary\n’); 


COMPARISON OPERATORS IN C 


In C, most of the symbols used to compare two numbers with each other are 
two characters long. A couple of them are different than in other languages, 
as you note from the table. 


> Greater than 

< Less than 

>= Greater than or equal to 
<= _ Less than or equal to 
== Equal to 

{= Not equal to 


Note in particular that if you wish to see if two variables are equal you must 
write two equals signs: 


if (a == b) 
printf(''they are equal \n'); 
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In C, nearly anything you write is a legal expression, and the expression 
if (a = b) /*mistake ! */ 


returns the value of a after assigning the value in b to it. This is the single 
most common programming mistake in the C language, and often difficult 
to spot because the compiler regards it as a perfectly legal statement! Note 
also that the “not equal” symbol is “!=” rather than the “<>” used in most 
other computer languages. 


Combining Comparisons 


If you want to perform some action based on two or more comparisons, you 
will need to combine their results. This is done using the logical operators for 
AND, OR, and NOT. 


& & AND 
| OR 
! NOT 


These represent the most commonly confused symbols in C. The single “&” 
and ‘|’ represent bitwise operations on a number. The double “& &” and 
**\|”? are operators used in combining two logical expressions: 


if ( (a ==b ) & ( c == d)) 
printf(''both are equal \n'); 


Note the distinction C makes between the NOT operator and the one’s 


hd a 


complement operator. The operator negates a logical value: soa TRUE 


66,99 


value becomes FALSE and vice versa. The operator inverts all the bits 


in an integer: all ones become zeroes and all zeroes become ones. 


THE SWITCH STATEMENT 


The switch statement provides a succinct way of making multiple choices 
when a variable might have one of a number of possible values. It has the 
general form 
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switch (variable) 


{ 

case CON]: 
statements; /“execute if variable == CON a | 
break; 

case CON2: 

case CON3: 
statements; /“execute if variable = CON2 or CON3%/ 
break; 

default: 
statements; /“execute if none of the above a 
break; 

} 


The variable must be an integer or character variable, and the case selection 
values must be constants. The default case is optional and no statement is 
executed if the variable does not match any constant and there is not any 
default statement. 

Note carefully the break statement after every case. If it is not included, 
the statements on the lines that follow will be executed. For example, 
suppose we wish to convert certain characters to their Greek equivalents. 


char c; /* variable containing a character “/ 
switch (c) 
t 
case ‘a’ 
c = 224; /* ASCII value for alpha in PC font */ 
break; 
case ‘b: 
c = 225; /* ASCII value for beta in PC font */ 
break ; 
} 


In this case, we do nothing to c if there is no match, so no default statement 
is needed. 

You can also use the break statement to jump out of the current block or 
loop, but this leads to code that can be very hard to follow, and this is not 
recommended. 
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THE ORNERY TERNARY OPERATOR 


The statement 


if ta > Bb} 
Z=a;3 

else 
z=b; 


can be more compactly written using the “?:” ternary operator: 
2=ia> b} T ae b: /*®* z is a if a *b, else z is b*/ 


Actually modern compilers generate the same code for either expression and 
the only criterion for choice between them is readability. On this basis, the 
ternary operator will not be used further in this text. 


INCREMENT AND DECREMENT OPERATORS 


Because C was developed when compilers weren’t as “smart” as they are 
today, a number of C’s constructions are designed to tell the compiler the 
simplest way to compile the code. Many of these terse operations are sur- 
prising to scientists used to working in other languages. 

You can increment or decrement any integer or long integer variable in 
the same expression that uses it in a calculation by either preceding or fol- 
lowing it with “++” or “--.” If the symbols precede the variable, it is incre- 
mented or decremented before it is used, and if they follow, the variable is 
changed after it is used. 


i+F; /* same as i = i + 1 a 
ep ies] = 123 /* put 12 in x[i] and increment i */ 
deat 8 ia /* decrement j and put the value “*/ 

/* of i in y[ i] * 


These auto-increment functions can be rather dangerous, since it is possible 
to write expressions containing several instances of a variable, and become 
confused about when the variable is incremented. 

Whenever you want to perform any of the simple arithmetic operations 
on a variable and put the result back into that variable, you can do that with 
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the combination operations that simply say perform the operation on that 
variable: 


j += 2; f* j= j+2 oe 
x *= 6; /* multiply x by 5 “y 
[ Het he /* subtract j from 1 i 
k /= 4; /* divide k by 4 a 
reg >>= 2; /* shift reg 2 places to the right “/ 
word <<=1; /* shift word 1 place left a 


Note that modern compilers would probably generate the same code from 
the longer expressions for the same operations, but these have a certain 
succinctness that makes them appealing when involved in complex 
expressions as we will see in the following section on looping. 


LOOPING STATEMENTS 
For Loops 
You can write loops in C using three different constructions. For loops 
where the lower and upper bounds are known in advance, the for loop is the 
simplest: 
for (i = 0; i < count; i++) 
x[i] = i; /* put the value of i in each element*/ 


Note that since arrays always start at zero and end one before the final 
dimension size, we start our for loop at zero and loop while the index is /ess 
than the final count. These for-loops can contain more complex operations, 
and are not limited to incrementing the index by |: 

| = Ceount 7 2): 1 += 2] 


1 


for (i = 0; 
xi] *= 3 


The for loop can also operate on a block of statements: 
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for ({ = @; | = count; i++) 
{ 
xfi] = yli]s 
Wi) = ye 33 
} 


In summary, the three statements in the for loop consist of the starting con- 
dition, the ending condition, and what to do at the end of each pass through 
the loop. Since the loop conditions are checked before the loop is executed, it 
is possible that in some cases the loop will not be executed at all. 


While Loops 


The while loop performs operations in the loop until the condition specified 
becomes true. As with the for loop, the condition is checked before the loop 
is executed, and the loop might not be executed at all. The while-loop has 
the general form: 


while (condition) 
{ 
statements; 


} 


It is generally used when a loop is to be executed an unknown number of 
times but will exit when some computed condition is fulfilled. 


factorial = 1; f"initialize factorial ss 
while (num > 0) 
{ 
factorial *= num;  /*multiply by current number */ 
num-- ; /*reduce num by 1 cy 
} 


You should note that a common programming error Is forgetting that the 
variables you are testing must have initial values before you begin the while 
loop. In the fragment above, num must have a positive, non-zero value for 
the loop to be executed. 
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The do-while Loop 


The do-while loop looks rather like the while loop: 


do 
{ 


Statements; 


} 


while (condition); 


It differs only in that the loop is always executed at least once since the test 
for the termination condition takes place at the end of the loop. You should 
only use it when you are sure that there can never be conditions when the 
loop should not be executed. As you might expect, you can usually write pro- 
grams to use either type of while loop, and the first type seems to be favored. 


POINTERS IN C 


The most unusual feature of C compared to other high-level languages is its 
use of pointers. A pointer is simply the address of a variable or of the begin- 
ning of an array. In C, the “&” operator means take the address of a vari- 
able, and the ““*”’ operator means get the value pointed to by the pointer: 


float x, ys “pe 7" 6 is a pointer to a a 
/* floating point number “7 
p = &x; /* get the address of x oF 
y = “p; /* y is assigned the same value as x */ 
/* and pointed to by p a 


Pointers are very commonly used instead of array variables, since they can 
be incremented as you pass through a loop, without the overhead of calcu- 
lating the base of an array and adding an index to it each time. 

#define MAX 100 

float x[MAX], “p; 

int is 


p = x; /* p points to beginning of array “*/ 
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si 


if /* zero out the array sf 


wt 


for (i = 0; i < MAX; i++) 
‘re = 


C automatically increments pointers by the amount suitable for the size of 
variable they represent: | byte for char, 2 for integer, 4 for float, and 8 for 
double on the PC, so you needn’t have any knowledge of these relative sizes. 
Note that this is entirely equivalent logically to 


for (i=0; i < MAX; i++) 
xi Tr) = Oy 


but is likely to execute more rapidly, since there is no array-indexing calcu- 
lation in each loop. 

Pointers are also used to point to memory that is allocated and de- 
allocated within a module using memory management functions such as 
malloc. 


#include <malloc.h> 
int iz 
float *x, *D: 
/* allocate 1000 floating pt numbers */ 
x = malloc(1000 * sizeof(float)): 


p= X; /* use p as variable ptr x / 
for (i=0; i < 1000; i++) 
"pee = Fi /* convert i to float and store am | 


Strings as Pointers 


Since strings are arrays of characters and since the name of an array is in 
fact a pointer to its first element, you should recognize that string variable 
names are in fact always pointers to the strings. 


char string[80], “ch; 


ch = string; /* set pointer to start of string af 
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CONVERTING BETWEEN DATA TYPES IN C 


C will automatically convert between type char and integers. It will make 
all other conversions, as well, but will warn you that it is making them. 
Thus, in the above example, we could have written 


“ott = (float)i; /*convert integer to float*/ 


and would have avoided an error message from the compiler. The conversion 
of variables from one type to another in C is called casting and is accom- 
plished by preceding the variable with the new type name in parentheses. 

Pointers have types associated with them as well. For example, the 
malloc function returns a pointer to variables of type void (a pointer to no 
type), and it must be cast to point to type float. This casting is important, 
since incrementing a pointer of the wrong type may increment it by the 
wrong number of bytes: 


float *x; 
/* x is a pointer to 1000 floats */ 
x = (float *)malloc(4000); 


FUNCTIONS IN C 


While many languages provide both subroutines and functions, the C lan- 
guage provides only functions. A C function can have many variables and 
can return a single value of any simple type as an answer. All functions are 
assumed to return a value of type int unless another type is specifically 
declared: 


float xsum( float a, float b) 
/* returns the sum of a and b */ 
{ 
float sum; /* local variable “*/ 
Sum = a + b; 
return(sum); 


/*----- main routine starts below---------- * 
void main() 


{ 


SHSOSOSSHOSOOSOSO OSS SSOSOHDOSOOSHOOSOOOCOOBOCCE 


59S SOG GGGOGOGHSOHSOOSOSOSOVOOSOSOSGORDOOSSEESD 


FUNCTIONS INC 25 


float x, y, tsum; 
2-0; 
y = 6.3; 
tsum = xsum(x, y); /*call the function */ 


} 


When you want to write subroutines that do not return values, you simply 
write functions of type void that return no value. 

Unlike many other languages, all arguments to a function are passed by 
value. In other words, a copy of the variable’s value is passed to the function, 
leaving the original in tact. This does not turn out to be much of a problem, 
however, because you can always pass a pointer to any variable to the func- 
tion, and it will then have access to the original data. This is particularly 
useful when you want to pass a whole array to a function. 


/* Function to sum up an array */ 
float arraysum(float *x, int count) 


{ 
float sum; 
int 13 
sum = 0.0; /* initialize sum ag 
for (i=0; i<count; i++) 
sum += “x++; 
return(sum); 


float x[100], sum; 
/** code to put something in array must go here**/ 
sum = arraysum(x, 100); /* add it all together */ 
} 


Note that an array name is actually exactly the same thing as a pointer. The 
address of the beginning of the array x is the same as the value of the 


pointer x. 
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Static and Automatic Variables 


Variables declared for use within a function usually exist only while the 
function is being called. Thus, if you call the function again later, a new 
space is created for this variable and the previous value will not be remem- 
bered. Such variables are called automatic variables. Since you usually are 
done with such variables when you exit from a function, you usually don’t 
care if the values are remembered. 

There are occasions, however, when you may call a function once to ini- 
tialize some variables, and again later to perform some calculations. In this 
case you want these variables to be remembered. In C these are called static 
variables and are denoted by preceding the variable type with the keyword 
Static. 


void statfunc(int a, float x) 
{ 


double gronch; /* automatic variable */ 
static int brunch; /* static variable a 3 


Such static variables turn out to be useful in the Presentation Manager 
where window procedures are called many times during the life of the 
window. 


Function Prototypes 


When you write a function that is called from within a module or, more 
important, from another module, the C compiler must know the number and 
type of arguments and the return type of the function. You provide these by 
simply declaring the function at the top of each module using the same dec- 
laration as you used at the beginning of the function, except that you follow 
it with a semicolon. 

If your function starts with this statement: 


void statfunc(int a, float x) 


you would put the following statement at the top of all modules that call that 
function: 


void statfunc(int a, float x); 
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Since this can lead to errors very quickly as you change functions, it is more 
common to put these declarations in an include file that you reference at the 
beginning of each module: 


#include ''statf.h'' 


where this file may include declarations for a number of related functions. 
A large number of include files are provided with your C compiler, which 
are typically kept in the subdirectory 


\incelude 


These define the variable types and return types for all of the C library rou- 
tines. The C library manual for your compiler will tell you which ones to 
include. A number of similar files having slightly different calling con- 
ventions are also stored in the directory 


\include\mt 


which allow C library functions to be called from multitasking programs. 

If you enclose the filename for the include file in angle brackets, C will 
look in the \include directory or that directory list defined by the DOS or 
OS/2 include environment variable. If you enclose the filenames in quotes, C 
will only look for them in the current directory. 


THE SCANF FUNCTION 


Until now, we have avoided explaining how to read in data from the key- 
board. This is because the scanf function requires the use of pointers. It has 
the form 


scanf( 2F Sd, &%, &]): 


where the format strings have the same meaning as they did for printf but 
the values passed to the routine are pointers to the actual variables. There is 
also an analogous routine sscanf that operates on a character buffer: 


sscanf(buf, "Sf %d'', &x, &j); /*convert from buffer”/ 
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As we noted above, strings are always pointers, so that if you are reading in 
data to a string, the name of the string array is not preceded with the “&” 
sysmbol: 


char st[80]; 
int 13 


scanf( ‘Sd %s'', €i, st); /* read integer and string */ 


FILE HANDLING IN C 


There are two sets of file handling calls in C: open, close, read, write and 
fopen, fclose, fread, fgets, fputs, fputc, fgetc. The first group uses an integer 
called a file handle, and the second a pointer to a structure FILE. Since the 
latter group operates at a higher level, allowing the reading of strings of 
varying length from a text file, we will used it in our examples. The former 
group is sometimes used when individual bytes of unknown type must be 
read. 


#include <stdio.h> 
PILE r 
char string[80]; 


f = fopen(''filename.ext'', ''r''); /*“open a file -read only */ 
i {ft l= NULL) 


begin 

fgets(string, 80, f);  /*read a string from the file*/ 
Felose(f); /*close the file xy 
end 


You should note that the pointer f will be NULL if the file can’t be found, 
and that performing an fclose on a null pointer will crash your program. 
Further, the fgets function reads a string to first end of line or end of file 
mark, and includes this new line character (\n) in the string that is read. 
Often you must write code to remove that character from the string. 
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GENERAL C LIBRARY FUNCTIONS 


There are a large number of functions provided with the compiler for many 
types of operations. These are described in the C Library Reference manuals 
provided with your compiler. When you call these functions, be sure to add 
the #include header files specified for that function in the reference manuals. 


STRUCTURES IN C 


The last topic in our survey of C is the structure. A structure is a group of 
related variables of various types that are kept together. This turns out to be 
a very important concept in OS/2, because descriptions of files, windows, 
and other internals are all kept as structures. To define a structure you 
simply begin by writing it out following the struct keyword, with all of the 


variables enclosed in braces: 


struct fblock 


t 
fiGsr Ks. V3 /*two fp variables*/ 
(Ae Ty. 13 /*two integers =) 
char name[80]; /*and a string ay 
}; 


The name fblock is the name of this structure and can be used to represent it 
without listing its elements again when we define actual variables of this 
structure type. Note particularly that the structure definition ends, like all 
statements, with a semicolon. Omission of this semicolon is a common pro- 
gramming error that leads to untold confusion by many compilers. 

Then to declare variables of this structure type, we simply write 


struct fblock Tl, f2; /*two structure variables = if 


Elements within a structure are accessed by adding a period to the struc- 
ture variable name and following it with the name of the element. 


fl.x = 4.32; /*floating element a 
fl.j = 12; /*integer element ard 
strcpy(fl.name, ‘'foo'); /*put string into structure */ 
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Pointers to Structures 


You can allocate space for structures dynamically in your C program using 
the malloc function. Since we don’t know the size of a structure in general, 
we can use the C sizeof function to calculate it for us. 


struct fblock “pf; /*pointer to structure */ 


fal locate space for a structure™/ 
pf = (struct fblock “)malloc(sizeof(struct fblock)); 


This returns a pointer to a memory space where the structure is to be 
located. A special character pair “->” has been defined in C to get the value 
of a structure element where the base name is a pointer to the structure 
rather than the structure itself. 


/*allocate space for a structure*/ 
pf = (struct fblock *)malloc(sizeof(struct fblock)); 


1 


prmex = 4.5} /*“assign value to element se 
strcpy(pf->name, ''fred''); /*copy string into structure */ 


THE TYPEDEF DECLARATION 


The typedef declaration provides a way for you to declare names for new 
data types. You could write 


typedef struct fblock 


{ 

Float x, y; /*two fp variables */ 
int 15 J3 /*two integers a 3 
char name[ 80]; /*and a string ey 


} FBLOCK, “PFBLOCK; 
Now you have defined the type FBLOCK as the type 
struct fblock 


and PFBLOCK as a pointer to that structure type. Then you can declare 
your variables and allocate structures more simply: 


FITTEST 


606 @ 
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PFBLOCK pf; /*pointer to structure */ 


/“allocate space for a structure”/ 
pf = (PFBLOCK)malloc(sizeof(struct fblock)); 


COMMENTS IN C 


Since C can be so terse, comments are absolutely required to make C pro- 
grams readable. As we noted earlier, a comment starts with “/*” and ends 
with ‘**/.” You can continue a comment for several lines, but this can lead 
to lost beginnings and endings of comments. If a comment describing a 
program’s purpose or function will carry on for a number of lines, it is cus- 
tomary to start each line with “*/*”’ and end each line with “*/” to make the 
comment stand out for the reader. Contrast the two examples below: 


/* This is a comment at the beginning of a program 
This program is used to read in columns of scientific 
data and display them on the screen as xy plots. Each 
successive column is displayed in a distinct color. */ 


i or see the second way below.... 7 
[Bowen amin en er aS SOR Sa ome See Sonne Ra eee sana a 
/* This is a comment at the beginning of a program */ 
/* This program is used to read in columns of scientific */ 
/* data and display them on the screen as xy plots. Each */ 
/* successive column is displayed in a distinct color. “*/ 
/ : a a eee Ee EERE at ae Se ena Sete ya Pee gE ae eT IE * / 


Since it is often useful to be able to “comment out” single lines of code in 
a program under development, recent C standards have also added the 
double slash (“‘//’’) as the beginning of a single line comment. Any line that 
starts with two slashes is treated as a comment 


c=atb; /* This line is compiled */ 
f7e = a + bs /* This line is skipped */ 
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THE C READABILITY DEFINITIONS 


The C language tends to be terse and either elegant or so compact as to be 
unreadable. To make programs more readable and maintainable, partic- 
ularly to those who may have started in other languages, we introduce the 
following “readability” definitions to replace some of the symbols that either 
do not print well or are hard to remember. The C preprocessor will automat- 
ically insert the correct C symbols before the compiler begins scanning the 
code, so there is no loss of generality in these symbol choices. 


JE®®EEX © Readability definitions ********exeexK 
#define begin { 
#define end } 
#define endif } 
#define endfor 3}. 
#define endwhile } 
#define OR | | 
#define AND && 
#define BitAND 6& 
#define BitOR | 
#define MOD % 
#define NOT | 
#define OnesComp ~ 
#define then /*then*/ 


These definitions are in our file cdefs.h, which we include in the code in the 
following chapters. 


MACROS IN C 


The #define statement in C can also be used to make some complex 
expressions appear simpler to the reader. Define statements that make use of 
arguments are called macros. For example, we could define a macro to get 
the upper 16 bits of a 32-bit word by 


#define UPPERWORD(a) (((a) >> 16) & Oxffff) 
and the max function is often implemented as a macro 


#define max(a, b) ((a) > (b) ? (a) : (b)) 
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STRUCTURED PROGRAMMING IN C 


A structured program is one that follows a few simple rules that make it 
easy to read and maintain. Some of these are: 


1. Each function or routine must have a clearly distinguishable purpose. 
You should set off each function within a module with a line of asterisks 
or dashes and start it with a comment explaining its purpose. 


2. Every routine should have only one entry and exit point. You should be 
able to start at the beginning of a routine and know that code will be 
executed starting there, and be sure that code at the end of a routine 
will be executed last. This precludes the use of goto statements that 
disturb linear program flow. Use if-then-else and while statements to 
control program flow. 


3. A loop or block should only exit at the bottom. While the goto and break 
statements could be used to exit prematurely from a loop, it 1s better to 
use flags and if statements instead. The same amount of code is gener- 
ated in either case and the code is easier to read. 


4. Loops should be indented, so their meaning is clear. Whether you choose 
to use braces or “begin” and “end” to replace the braces, you should 
align the block of code under these delimiters and indent the whole 
block. Be sure to put spaces between all variable names and their opera- 


tors. 
/*---good indentation and spacing --------------- oy 
max = 0; /*initialize max a 
for (7 = 03°97 = 105 144) 
begin 
if ( x[i] > max) then /*look for largest value*/ 
begin 
max = xii]; /*save the new maximum */ 
isave = i; /*and save its index at i 
end 
end 
/*---another common indentation style------------ a 
max = 0; /*initialize max a i 


for (i = 0; i < 10; i++) f{ 


34 A BRIEF INTRODUCTION TO THE C LANGUAGE 


if ( x[i] > max) { /*look for largest value*/ 


max = x[i]; /*save the new maximum */ 
isave = i; /*“and save its index ay 
} 
} 
/*----harder-to-read indentation and spacing---*/ 
max=0; 
for (i=0;1<10; i++) { /*no comments either*/ 


if (x[i]>max) 
{max=x[ i]; 
isave=i; } 


} 


5. Avoid program “gullibility.”” Be sure that you do not make any unwar- 
ranted assumptions about the validity of the variables you will be 
working with. Don’t assume that the file exists, that the value is non- 
zero, or greater than zero, or that it is initialized. For example, the code 
below may not find the correct max: 


for (i = 0; i < 10; i++) 
begin 
if ( x[i] > max) then /*“look for largest value*/ 
max = xt]; 
end 


because max is never initialized before the search begins. 


DEBUGGING A PROGRAM WITH CODEVIEW 


You can debug any C program compiled with IBM C/2 1.1 or Microsoft C 
5.1 with the protected mode CodeView debugger: CVP. To run CodeView, 
you must have the statement: 


POPL=TES 


in your CONFIG.SYS file. You should have the sources of all the C 
modules in the same directory as the program you are debugging, and you 
must compile the code with the /Zi switch to generate debugging informa- 
tion. Then, you must use the /CO linker switch to tell it to include line 
number and symbolic information in the executable file. During develop- 
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ment, you commonly use both these switches all the time. When the 
program is complete, recompiling and relinking without them will make a 
much smaller program, which will run without IOPL=YES being set. 

To debug the program HELLO.EXE, simply type 


CVP HELLO 


CodeView will start and display the first lines of C code. It will also display 
the menu items: 


File View Search Run Watch Options Language Calls Help 


You can select any of these items with the mouse, or by holding down the 
Alt key and pressing the first letter of the menu item. For example, Alt-F 
pulls down the File menu. 

You can then step through the program, insert and remove breakpoints, 
and examine values of variables. 


PgUp Move up a page in the code. 

PgDn Move down a page in the code. 

F2 Toggle the display of registers on and off. 

F3 Switch between C, assembler, and mixed C-assembler displays. 
F4 Switch to the output screen. This will switch to PM screens 


when you debug PM programs. The CodeView screen returns 
in 4 seconds. 


F5 Begin or continue executing the program. 


F6 Move the cursor back and forth between the code window and 
an immediate window at the bottom. 


F8 Step through the code. 

F9 Set or clear a breakpoint. 

F10 Step through the code without jumping to any called subrou- 
tines. 


The key to using CodeView is to place a breakpoint at the first place 
where you wish to see what is happening. Then, start your program using F5 
and when the breakpoint occurs, you will have a display of the C language 
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code with the current instruction line highlighted. You can then watch the 
contents of any variable by name by pressing Ctrl-W and typing in the name 
of the variable. You can watch up to 10 variables at once and see how each 
changes as you step through the code. You can set additional breakpoints 
with F9 and remove old ones by putting the cursor on that line and pressing 
F9 again. You can also insert watchpoint expressions and have the program 
break when that expression becomes true. This does slow down the program 
execution significantly, however. 

If your program has a number of modules, you can open another C 
module specifically by pressing Alt-F and then pressing “O” for Open and 
typing in the filename including the C extension. You can also go directly to 
that routine by pressing F6 to go to the command line at the bottom and 
typing the command “‘V”’ followed by the name of that function. 

To exit at any time, simply press Alt-F followed by “X.” 
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3 Memory Management 
Under OS/2 


Memory management in IBM C/2 and OS/2 is tied closely to the architec- 
ture of the 80286 microprocessor. While the 80286 can address up to 16 
megabytes of memory, it is limited to addressing 64K segments at a time. 
This is because addressing is done through two 16-bit registers called the 
segment register and the offset register. Since the offset is limited to 16 bits, 
you can only refer to 65536 different bytes without changing the segment 
register. This leads to the concept of different memory models where dif- 
ferent restrictions are placed on the amount of memory you can access. In 
addition, the 80x86 microprocessors specifically distinguish between 
memory for code and memory for data by using different segment registers 
to point to code segments and data segments. 


MEMORY MODELS 


There are five memory models supported by most C compilers using 
switches invoked at compile time: 


small The code and the data are limited to 64K bytes each. 
medium Has multiple code segments but only one data segment. 
compact Has a single code segment but multiple data segments. 


oF 
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large Has multiple code and data segments, but each data 
segment is still limited to 64K bytes. 


huge Has multiple code and data segments, and data segments 
may be larger than 64K bytes. This is useful for han- 
dling large linear data arrays. 


In scientific programming we will be concerned only with the large and huge 
memory models. In the large model, no single data element may be larger 
that 64K bytes or 16K floating point numbers, but there can be many such 
arrays, while in the huge model, there are no limits on data size. There is, of 
course, a small difference in performance between the two models, since the 
compiler must generate code to increment both the offset and the segment 
register in huge model programs. It turns out, however, that in most modern 
workstations this difference is not noticable. 


NEAR AND FAR POINTERS 


Most C compilers for the PC add the special keywords near and far to the 
language to define the characteristics of data pointers. A near pointer is a 
short or 16-bit pointer and can only point to a variable or array in the 
current data segment. A far pointer can point to data in another segment 
and those data can be as large as 64K bytes. In addition, a huge pointer is a 
special far pointer that the compiler can use to point to data arrays larger 
than 64K bytes by manipulating the segment and offset registers. These 
keywords can be used to modify data types regardless of which overall 
memory model you are using: 


near. int “es /* a near integer pointer */ 
float far “p; /* a far floating pointer */ 
huge double “d; /* a huge double pointer */ 


COMPILER SWITCHES 


The following uppercase switches can be used to generate code in the various 
- memory models: 


SGSOSOHSSSOHOOSOHOSSOOSOSOSOOOCHCOCOCCCCCLEE 
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/AS_ small model 
/AM medium model 
/AC compact model 
/AL_ large model 
/AH_ huge model 


In addition, the IBM and Microsoft compilers recognize lowercase character 
switches that you can use to generate customized memory models. There 
must be three lower case characters in such switches, one for code pointer 
size, one for data pointer size, and one for segment setup when the program 
starts. The three letters can come in any order, but to simplify the examples 
we will list them in the order code-data-segment: 


code data segment 
S n d 
| f u 

h Ww 


Code Pointers: s and |. The s option means produce small code pointers 
and the | option means produce large code pointers. 


Data Pointers: n, f, or h. The n option produces near data pointers 
(small) the f option produces far data pointers (64K limit) and the h option 
produces huge data pointers. 


Segment setup: d, u, or w. The d option indicates that the stack 
segment (SS) equals the data segment (DS) on entry. This is the default for 
all normal programs. The u option tells the compiler to reserve different 
segments for the stack and data segments. This is the usual case for Presen- 
tation Manager programs. The w option sets up separate data and stack seg- 
ments but does not load the data segment register on entry to the program. 
This is the usual case for dynamic link libraries. 
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PROTECTED MODE PROGRAMMING 


OS/2 uses the protected mode of the 80286 and 80386 microprocessors. In 
this mode, the data segment registers are not loaded with a memory pointer, 
but with a selector value that is an offset into a selector table. The table con- 
tains the actual physical address of the code or data. This additional step is 
used so that the register contents do not have to change during memory 
management operations, which may result in the data being moved around 
in memory. This takes place completely transparently to the program. 

The other main advantage of protected mode is that you cannot 
accidently address or change data outside the data area reserved for you, 
because data area limit registers are also set when you obtain memory from 
the system. If you attempt to address outside these limits, the processor will 
generate an “exception,” which in the case of OS/2 will cause a “TRAP D” 
error to be displayed. This error will terminate the program, but 
nondestructively, since no other memory regions can be damaged by the 
error. 


ALLOCATING MEMORY FROM C 


There are a number of memory allocation routines provided by the C run- 
time library, that you can use to acquire memory blocks for your data. These 
should be used in preference to those provided by OS/2 when possible, since 
they make your program more portable to future operating system versions. 
All of these functions return a pointer of type void, which you must then cast 
to be a pointer of the correct type. 


malloc(int size) returns a near or far pointer, depending of 


memory model. 


_fmalloc(int size) returns a far pointer regardless of model. 
_nmalloc(int size); returns a near pointer regardless of model. 
halloc(long size, int vsize); returns a huge pointer to an array of size 


elements, each vsize bytes long. 
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Now there is no guarantee that huge data arrays larger than 64K will have 
their segments contiguous in physical memory, and, in fact, the OS/2 func- 
tions that these C functions call actually obtain selectors to 64K segments 
and a selector increment between segments. However, all this selector arith- 
metic is handled automatically by the C compiler, and there is no need for 
the data to be physically contiguous unless you are doing data acquisition 
using some hardware feature of an acquisition card. We will deal with this 
in the chapters on writing device drivers for OS/2. 


OS/2 MEMORY ALLOCATION FUNCTIONS 


All of the OS/2 system functions start with the prefix “Dos.” This is meant 
to indicate that they are operating system functions and that they will also 
work in the DOS compatibility box, but they are not, strictly, DOS func- 
tions. The C-library routines listed above call those OS/2 functions to allo- 
cate memory. The lower-level functions for allocating memory directly are 
discussed below. For most applications, you will probably never need to use 
these functions directly, but it is useful to see what the C library is doing 
under the covers in case a memory protection fault occurs that you can’t 
explain. 

In OS/2 terminology, when you allocate memory, OS/2 returns a 
selector value that is the value of a location in the descriptor table. To 
convert a descripter to an address you must make it the upper 16 bits of a 
32-bit pointer. The macro MAKE P is provided to do this: 


float *x; 
x = MAKEP(sel, 0); /* x is now a pointer 7 


/* to the address selected */ 


The memory allocation functions are 


DosAllocSeg(size, &sel, fl); /*“returns selector to memory*/ 
DosReallocSeg(size, sel); /*change the size of segment*/ 


DosFreeSeg(sel); /*free the allocated segment*/ 
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where 


size 


sel 


where 


numsegs 


@@eee@¢ 


is the number of bytes to allocate. This can vary from 1 ¢ ) 


WY 
to 65535 bytes and a value of zero means 65536 bytes. 
a, 
is the 16-bit selector value obtained when memory is, 
WY 
allocated. 
wy 
can have the values 7 
WS 
0x0001 the segment is shareable through iL) 
DosGiveSeg 
0x0002 the segment is_ shareable through Y 
DosGetSeg WY 
0x0004 the segment may be discarded in low- Y 
memory situations 3 
0x0008 the segment may be decreased in size, even an 
if shared. WY 
Huge memory is allocated using WY 
DosAllocHuge(numsegs, size, &sel, /*returns selector to */ Y 
maxsegs, flags); /* a huge region */ @ 
DosReal locHuge(numsegs, size, sel); on 
YW 
YW 
is the number of 65536-byte segments requested. &) 
is the size of the last non-64K segment. oe, 


Size 


maxsegs 


is the maximum number of segments you may reallocate \V 
to include. 


< 


The selected sel that is returned is a huge segment selector, but since the\_) 
segments allocated may not be continuous in memory, it is necessary to find 
out the number that must be added to the selector to get the next segment 


selector. This is done with 


DosGetHugeShift(gshift); 
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where shift is the number of places you must shift a bit left to get the value 
to add to one selector to access the next selector. This is all handled auto- 
matically from C, however, for arrays that you declare huge. 


Suballocation 


OS/2 1.2 allows you to access about 1400 different selectors, and thus you 
can only make about 1400 calls to DosAlloc. Since many times you only 
need a small amount of memory for a short time, OS/2 provides a method to 
allocate a large segment of memory and then suballocate it into small pieces 
as needed. This is in fact what the malloc call does automatically. 


al. 
aN / 


/*jnitialize a segment for suballocation 
DosSubSet(sel, 1, size); 


/*get offset for size bytes*/ 
DosSubAlloc(sel, &0ffset, size); 


/*free sub-allocated memory*/ 
DosSubFree(sel, offset, size); 


»999 


i 


| Writing a Simple Multi- 
thread Program 
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©) In this chapter we will write a simple multithread program that prints a 
) message once every second. In one thread, a timer will run and print mes- 
sap SABES, and in the other thread, we will monitor the keyboard. 
The program first starts a timer thread. This timer thread will send 
“ticks” to a routine that will print a message each time the tick occurs. 
) Meanwhile, another thread will monitor the keyboard and put any charac- 
a ters that are typed into a structure. This structure is then monitored by the 
same routine that is printing the tick messages and will exit if the letter “‘q”’ 
is struck. To keep our examples simple, we will not use the Presentation 


O) Manager in this first example. 
‘ah: 


©) SEMAPHORES 


In OS/2 a semaphore is a memory location that can be accessed by more 
than one thread or process. Semaphores have only two values, called “‘set”’ 
©) and “cleared” or one and zero. There are two types of semaphores in OS/2: 
@) RAM semaphores and system semaphores. RAM semaphores provide faster 
access to their contents, because they are actual memory addresses. System 
semaphores are created and opened like files and can be used by processes 
© that do not share memory. In this example, we will use system semaphores 
™) because these communicate with the system timer functions. Semaphores 


a@ are explained in more detail in Chapter 20. 45 


om 
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To create a system semaphore, we use the call 


DosCreateSem(exclusive, &hSem, szName); 


SO@eeede 


where 
exclusive is 1 if only this process can access the semaphore and 0 if WY 
it can be shared. & 
& hSem is a pointer to where the handle to the semaphore will be\_) 
returned. 
a, 
szName is the name of the semaphore. This is a zero-terminated(_ 
ASCII string like a filename that must contain the path 
name “\SEM\.” 
; Ye 
Then to set the semaphore we will use the call 
Ly 
DosSemSet (hSem) ; 
Y 


The timer function will clear the semaphore every time we set it and we willG) 
simply wait, trying to change the semaphore from cleared to set. We can 
only set the semaphore when the timer has cleared it, and thus the call 
DosSemRequest(hSem, timeout); pe 
will block the execution of that thread until the the semaphore is cleared and 
it can reset it. The function will exit after timeout milliseconds or will block 
the thread indefinitely if timeout is set to -1. WY 
WV 
CREATING A NEW THREAD Y 
WwW 
To create a new thread we simply use the _beginthread call, passing it the, 
address of the C function that is to be executed and the address of a stack of 
at least 2000 bytes: 


stack = malloc(2000); /*allocate stack memory*/ — 

_beginthread(Procedure, stack, stksize, arg); /*start it */ WW 

where WO 

Procedure is the address of the procedure to be executed by the new 
thread. 
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stack is the pointer to an array of at least 2000 bytes that is 
used by the new thread. 


stksize is the size of the stack in bytes. 


arg is an argument that is passed to the new thread. Usually 
this is a pointer to a structure of several data values, or a 
pointer to a value that the thread is to change. 


You can also create a thread with the OS/2 call DosCreateThread, but if 
you do, you cannot make calls to a number of C-library functions, such as 
printf or sprintf. The C function —beginthread correctly initializes the C 
library and then makes its own call to the DosCreateThread function. 


HUNGARIAN NOTATION 


The above examples illustrate the concept of “Hungarian” notation in 
naming OS/2 variables. The notation was named after Microsoft pro- 
grammer Charles Simonyi, who developed it. This notation scheme prefixes 
variable names with one or two lower-case characters describing the variable 
type and purpose. Some of the more common variable prefixes include: 


h A handle to an OS/2 object: timer, semaphore, window, etc. 
SZ A zero-terminated ASCII string: the usual C string type. 
Ip A long pointer to a variable. 


THE MAIN TIMER ROUTINE 


The main routine in our TIMER program will simply create and set the 
semaphore, start the timer, create a thread and loop looking for the char- 
acter “q’’ and print the message “‘tick”’ each time the semaphore clears and 
can be reset. 


void main() 

begin 
unsigned char “stk, c; 
HT |IMER TimeHandle; 
HSEM hSem ; 
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/*“create a system semaphore”/ 
DosCreateSem(1, &hSem, ''\\SEM\\TIMER.TIM'') ; 


/*set the semaphore high */ 

DosSemSet (hSem) ; 

/*start the timer with 1 second ticks “/ 
DosTimerStart(1000L, hSem, &TimeHandle); 
printf(''Started timer at 1000 msec intervals.\n'); 


/*Create a keyboard monitoring thread */ 

stk = malloc(2000) ; /*get stack space “*/ 
_beginthread(KeyTest, stk, 2000, &c); /*pass address of c*/ 
printf(''‘Created second thread \n'); 


do 
begin 
DosSemRequest(hSem, -1L); /*block thread until set sem*/ 
printf(''tick\n’); /*“message at each semaphore “/ 
end 

while(c != ‘q'); /*“other thread will change this*/ 


printf(''Exiting \n_); 
DosExit(1, 0); /*end all threads 
end 
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WAITING FOR THE SEMAPHORE 


The inner do-while loop simply issues calls to the DosSemRequest and waits; \ 
for the semaphore to clear. In the outer loop, it checks the current value of 
the character c whose address was passed to the keyboard thread and exits 


when it becomes “‘q.”’ 


THE KEYBOARD THREAD 


Finally, the thread that examines the keyboard simply loops “forever” 
calling the function getch, which has the form 


(™, 
om 
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cm 

M “c= getch(); /*get char from keyboard */ 

) where *c refers to the contents of the address c. The entire routine is simply 


) void KeyTest(char *c) 


am /* This thread waits for characters to be struck and a 
/* stores them in the character variable whose address a 
/* is passed in the call * / 
begin 
an °° 
“c= geten(); /* get char from keyboard — */ 
Mwhile (*c != 'q'); /* and check for 'q' a 
a end i" exit af 1 16. *e’ * / 
o 
ao EXITING WITH DOSEXIT 
on 


The DosExit function is used to terminate a program having a number of 
threads. The call has the form 


oy DosExit(action, rcode); 
O where 
‘a . e ° . 
action is 1 if you want to terminal all threads and O if you only want 
to terminate the current thread. 
reode is the return code you wish to pass from the program to the 
‘a system. 


O this call allows us to make sure that all threads terminate when the 
) program is finished. 


c™ 


} 


COMPILING WITH IBM C/2 
ro 
The IBM C/2 compiler requires that you define every function that you will 
call with a function prototype or definition of the type of each argument and 
the function’s return type. All of the OS/2 functions are defined through the 
amuse of the include file os2.h. This file is actually a small header file con- 
taining a number of conditional includes that depend on whether various 
symbols are defined or not. These symbols are used as follows: 


399 
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#define INCL BASE /* DOS and Kbd functions */ 
#define INCL PM /* Win PM calls / 
#define INCL_GP| /* Graphics calls uy 
#define INCL DEV / * / 


* device calls 


#include <os2.h> f* 
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0S/2 calls defined ze f 


In this simple example, we are using only the BASE calls. In addition, every 
function in our program must have a function prototype definition at the top \_) 
of the module. Here, we need to define the routine KeyTest. We also need 

are ww 
the C-definitions file 


C. 


cdefs.h 

and the files 

Stdio.h 

where printf is defined, 

conio.h 

and 

process.h 

where _beginthread is defined, and 
stddef.h 


and 
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malloc.h 


where getc and malloc are defined. The correct include files to use for each 
library call are listed in the C Language Reference manual provided with( ) 


( 


your compiler. 


/* Process with 2 threads executing */ 


#define INCL BASE 
#include <os2.h> 
#include <cdefs.h> 
#include <stdio.h> 
#include <malloc.h> 
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o 
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O) #include <conio.h> 
#include <process.h> 


#include <stddef.h> 

m™ 
/*function prototypes (required)*/ 
void KeyTest(char “*c); 


al Jb we we oe oe I I ee I I I I I I 
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om 


© PASCAL-STYLE FUNCTION CALLS 
rm 


The usual C programming style allows you to write functions that have vari- 


I we we ot te I I 
WIN IN IN INES IN INNS f 


able numbers of arguments, because the number of arguments passed to the 
'__/ function is known only to the calling program. On a machine level, the argu- 
) ments are pushed onto the stack before the function is called and removed 
om from the stack by the calling program when the function returns. Calling 
functions in this way can lead to larger code modules, since every single call 
~’to a function must provide its own stack cleanup after the return from the 
©) function. | 
a, The Pascal-style function call is one in which the called routine removes 
_ the arguments from the stack before returning. Since the stack is cleaned up 
only in one place, the generated code in more complex programs can be as 
) much as 10-20% smaller. For this reason, as well as for more internal 
>) reasons, all OS/2 functions are called in Pascal style, as well as all functions 
that you write that are to be called from OS/2, such as thread procedures 
and window procedures. 


oo» 
>» COMPILING THE TIMER PROGRAM 


« The command for compiling this program is 


cl /c /AL /W2 /G2sc /Os /Zpe timer.c 


f 


where 


Se 
(or) 


means compile but do not link. 


/AL means compile using the large memory model. 
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/W2 means generate error messages at warning level #2. 

/G2 means generate code for the 80286. 

/Gs means remove stack probes. 

/Ge means generate Pascal-style function calls. 

/Os means optimize for size. 

/Zp means pack structure members. 

/Ze means enable language extensions (such as the _ pascal 
keyword). 


The Multithread Include Files 


0660000800800 OE 


A library is provided with the C compilers called LLIBCMT.LIB, which \__ 
contains the multithreaded \ibrary functions. These functions store no ¢~ 
values internally and can be called from several threads at once, since they 

are totally reentrant. All of these functions have Pascal-style calls and WY 
require different function prototypes in the header files. These header files \ 
are stored in the &) 


include\mt WY) 


subdirectory and you can make them the default for your use by setting the \y 
environment variable INCLUDE as follows: 


set INCLUDE=c:\include\mt;c:\include; 


OOOe 


LINKING THE TIMER PROGRAM 


When you run the IBM Linker/2 you will find that it requests a name for a 

.DEF file as well as the names of .OBJ and .LIB files. This .DEF file con- 
tains the stack size as well as other information that we will use under the V 
Presentation Manager in later chapters. If you simply type 


link timer 


the linker will ask you for the following: 


©@00ee0¢ 
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Run File [TIMER.EXE]: 

List File [NUL.MAP]: 
Libraries [.LIB]: 
Definitions File [NUL.DEF]: 


You can press the Enter key for each of the above questions except the last 
two. You must enter the names of the libraries OS2.LIB and 
LLIBCMT.LIB and the name of the .DEF file, usually TIMER.DEF. This 
file contains the following minimum information: 


NAME TIMER 
DESCRIPTION ‘Timer Sample Program: 
STUB 'OS2STUB.EXE' 


CODE MOVEABLE 
DATA MOVEABLE MULTIPLE 


HEAPSIZE 1024 
STACKSIZE 4096 


The NAME statement should correspond with the name of the executable 
program file. The DESCRIPTION statement inserts text into the program 
module, and can be used to embed copyright statements and other similar 
information. The STUB statement appends DOS-executable code to the 
program, and the file OS2STUB.EXE contains the statement “This 
program will not run in DOS mode.” The CODE and DATA statements 
define the attributes of code and data segments of the program and are 
simply set to their default values for this program. Finally, the HEAPSIZE 
and STACKSIZE statements allow you to reserve a predetermined amount 
of space for the program’s heap and stack. Arrays and automatic variables 
are generally taken from the stack space and global and static variables 
from the heap. 


USING AN AUTOMATIC RESPONSE FILE 


You can use an automatic response file to answer the linker questions by 
simply making a file called TIMER.L containing 
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timer.obj /A:16 /NOD 
timer.exe 

timer .map 
}libemt.1]ib+ 

os2.1lib 

timer .def 


leaving a blank line for the default libraries. Then you can simply type 
link @timer.1 


to link your file. 


USING THE MAKE UTILITY 


The MAKE/2 program provides a simple method of compiling and linking 
programs containing multiple modules, where the MAKE program checks to 
see if the current file has a later time and date than any of the files it 
depends on. The syntax for declaring these dependencies is 


file: depfilel depfile2 depfil3 
commands to execute 


In addition, if MAKE/2 discovers that one of the dependent files is itself 
dependent on other files whose dependencies are declared later in the make 
file, it will compile those first. The complete MAKE file TIMER.MAK for 
this simple TIMER example is 


## TIMER MAKE file 
timer.exe: timer.obj 
link @timer.1 /A:16 /NOD; 


timer.obj: timer.c 
cl /c /AL /W2 /G2sc /Os /Zpe timer.c 


To us MAKE, you simply type 


MAKE TIMER.MAK 


and the program will scan all of the target files. If timer.exe is older than 
timer.obj, it will examine timer.obj’s dependencies and if timer.obj is older 
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than timer.c, it will compile timer.c using the command given. Then it will 
link timer.obj according to the timer. file and make timer.exe. 

While using MAKE for this simple example seems trivial, it can be a 
very valuable program development tool when a program has several 
modules and you change only one of them. Then MAKE will recompile only 
those modules that have changed. 

The example shown here is specifically for the version of MAKE pro- 
vided with IBM’s C/2 1.1 compiler. Other versions of MAKE, including 
those from Microsoft, may analyze the dependencies between files differ- 
ently and expect the final target file last rather than first. Check the doc- 
umentation for your version of MAKE if these examples do not work 
correctly. 


RUNNING THE TIMER PROGRAM 


To run the program under OS/2, simply type TIMER at the prompt. The 
program will print out 


C>TIMER 

Started timer at 1000 msec intervals. 
Created second thread. 

tick 

tick 

tick 

tick 

tick 


until you press “q.” Then it will print 


Exiting 
C> 


and exit back to OS/2. 
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5 Using the Presentation 
Manager 


The Presentation Manager (PM) is one of several possible screens that can 
run under OS/2. It provides a consistent visual interface for programs along 
with device-independent graphics. In addition, it features pull-down menus, 
mouse interaction, and the ability to run tasks or programs in multiple 
windows. 

There are some fundamental programming differences when you operate 
in a windowing environment. In particular, the size and position of the 
window owned by your program are managed by the system. You as a user 
can grab and resize or reshape a window, or convert it from a window to a 
small icon pattern at the bottom of the screen. However, whenever a window 
is moved or sized, the system redraws its borders and menu bars, but you as 
the programmer must repaint the contents of that window. 

This is a fairly important distinction from other types of graphics pro- 
grams, where you can be more or less certain that the screen is the way it 
was when you drew it. Here, any window may attempt to be resized, which 
will affect other windows’ position and contents. When such resizing occurs, 
your window receives a PAINT message, along with coordinates that tell 
you which part of the window needs redrawing if only part of the window 
needs to be repainted. The upshot of this is that windows must be prepared 
to loop, checking for messages that must be acted on at all times. 

Each window has associated with it a window procedure, which is in fact 
a subroutine that is called by OS/2 when an event occurs that might affect 


om 
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that window. When the window procedure is called, the four arguments that 
are passed to it are called a window message. 


WINDOW MESSAGES 


In the Presentation Manager, a message consists of four values that are sent 
to the windows procedure: 


hWnd the handle for that window (16 bits) 
message a message number (16 bits) 

mp1 a 32-bit parameter value 

mp2 a second 32-bit parameter value 


As before, a handle is just a number by which an object in the PM is identi- 
fied. The types of messages that may be received by a window include: 


e Window creation 

e Window resizing 

e Window repainting 

e Mouse movement 

e Mouse buttons 

e Keyboard character 

e User-defined messages 


e Messages from other windows 


WINDOW DATA TYPES AND CONSTANTS 


The PM include files define a large number of data types and constant 
values that are used throughout PM programming. As is customary in C, all 
constants and defined types are represented entirely in uppercase, while var- 
lables are represented in lowercase or a mixture of cases. 
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OS/2 Data Types 


LONG 
ULONG 
SHORT 
USHORT 
CHAR 
UCHAR 
MPARAM 
MRESULT 
FAR 
PASCAL 
BOOL 
BYTE 
VOID 
PVOID 


a 32-bit signed integer, same as type “long” 

a 32-bit unsigned integer 

a 16-bit signed integer, same as type “int” or “‘short”’ 
a 16-bit unsigned integer, same as type “unsigned int” 
same as type “char” 

an unsigned char 

a 32-bit message parameter value 

a 32-bit message reply value 

same as “far” keyword 

same as ““pascal’’ keyword 

a short value that can be either TRUE or FALSE 

an unsigned char type 

the “‘void”’ data type 


a pointer to a value having the void data type 


OS/2 Structures 


Some of the more common structures used in OS/2 include: 


RECTL 


POINTL 


HANDLE 
HWND 
HPS 


The dimensions of a rectangle in four integer values: 
xLeft, xRight, yBottom, and yTop. 


The x,y coordinates of a point in two long values: 
pointl.xand pointl.y. 


a handle toa PM object 
a handle to a window 


a handle to a Presentation Space 


60 USING THE PRESENTATION MANAGER 


HMQ a handle to a Message Queue 


HSEM a handle to a Semaphore 


PM Messages 


A large number of values representing bit fields, colors, and messages have 
been defined as constants. The most important of these are the following 


WM_ messages: 
WM_CREATE 


WM_PAINT 
WM_CLOSE 
WM_QUIT 
WM_SIZE 


WM_CHAR 


WM_COMMAND 


WM_MOUSEMOVE 


WM_BUTTONIDOWN 


A window is being created, but not yet 
shown. 


The window needs to be repainted. 
The window is about to be closed. 
The window is being closed. 


The window is being resized. Mp1 contains 
the old x and y sizes, and mp2 contains the 
new x and y sizes. 


A keyboard character has been struck. The 
upper word of mp2 contains the character 
code and the lower part the scan code. 


A menu command has been selected. Mpl 
contains the command value. 


The mouse has been moved. The upper 
part of mpl contains the x-position and the 
lower part the y-position. 


The left mouse button has been depressed. 
The upper part of mpl contains the 
x-position and the lower part the y-position. 
Analogous messages for button-up and for 
button 2 also exist. 
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STRUCTURE OF A PM PROGRAM 


Presentation Manager programs are constructed so that the central loop is a 
window procedure, or function that is called by OS/2, passing to it the four 
arguments that constitute a message. For a window procedure to run, you 
must tell OS/2 its address and some general information about the window. 
This is done by registering the window class. In addition, you must create a 
message queue, an internal structure where messages accumulate before 
they are received by various windows. Thus, the overall structure of a PM 


program is: 
1. Initialize the PM facility (WinInitialize). 
2. Create a message queue (WinCreateMsgQueue). 
3. Register the window class by name (WinRegisterClass). 
4. Create the window and display it (WinCreateStdWindow). 
5. Loop getting messages, until WM_QUIT is posted (WinDispatchMsg). 
6. Destroy the window and the message queue (WinDestroy...). 
7. Terminate the program (WinTerminate). 


All of the messages that are dispatched end up being received as arguments 
by your program’s window procedure. Within the window procedure, you 
simply interpret the messages using a switch and take action as necessary. 


A SIMPLE HELLO PROGRAM 


To illustrate how to write a simple program to display a message on the 
screen, let’s design a program to display “Hi there” on the screen in blue 
letters on a black background. The coordinates of the window start with 
(0,0) in the lower left corner, and we will display our message at (50,50). In 
this first program we will only process the WM_PAINT message and leave 
all other messages to be processed by the default message-handling routine. 
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Initializing the PM and the Message Queue 


The first thing we must do in a PM program is to initialize the Presentation 
Manager services and set up a message queue. This is done in the first part 
of our program as follows: 


#define INCL PM 
#include <os2.h> 
#include <cdefs.h> 
#include <string.h> 
#include ‘‘hellojl.h- 


/* required function prototypes */ 
MRESULT FAR PASCAL HelloWndProc( HWND, USHORT, 

MPARAM, MPARAM ) ; 
void cdecl main(void); 


[REMI IED BE BN es BRS HE Pe eB a WN NER ROS BAER AS BAAS WN TOUR ON PS VaR OREN INE NEN OAR TSE 

void cdecl main () /*€ main routine™/ 

begin 
QMSG qmsg; /*“defining a message queue “/ 
HAB hAB ; /*handle to anchor block * f 
HMQ hmqHe 1 lo; /“handle to message queue */ 
HWND hWnd; /*client area window handle*/ 
HWND hFrame ; /*frame window handle “J 
ULONG flCreate; /*window create flag bits ak 


hAB = WinInitialize (NULL); /*init and get anchor handle*/ 
hmqHello = WinCreateMsgQueue(hAB, 0); /*“create msg queue “/ 


The WinlInitialize function returns a value called a handle to an anchor 
block, which is used in the following WinCreateMsgQueue call. This handle 
is also used in some timer and closing calls. 


Register the Window Class 


Then we register the window class as a class name. These class names are 
zero-terminated ASCII strings containing any desired name. Usually you 
relate the class name to the program or window’s function. 
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/*register the Window class*/ 


WinRegisterClass (hAB, /*“handle to anchor block */ 
(PCH)''Hellov, /*‘name of window class “*/ 
(PFNWP)HelloWndProc, /*address of window procedure “/ 
CS _SIZEREDRAW ICS SYNCPAINT, /*use these flags xy 
a a /*“number of ''extra'' bytes*/ 


In this call, we pass the anchor block handle hAB and the class name 
“Hello,” and the address of the window procedure HelloWndProc. Then we 
set two style bits, CS_SIZEREDRAW and CS_SYNCPAINT, which say 
that the window should receive a paint message whenever the window is 
resized, and should be repainted synchronously. A _ synchronous-paint 
window will be redrawn whenever a paint message occurs, while an asyn- 
chronous window will be redrawn after there are no other messages in the 
queue, so that several paint regions may be combined into a single operation. 
The final argument is the number of extra bytes that should be reserved as 
part of the window structure. These bytes can be used to pass arguments to a 
window, obviating the need for global variables. For the moment, however, 
we will simply set this value to zero. 


Create the Window and Display It 


To create the window, we simply call WinCreateStdWindow, passing it a 
number of style bits and the class name of the window. We also include the 
title to be put across the title bar of the window. This function actually 
creates two windows, a frame window and an interior window called the 
client window, which 1s a child of the frame window. 

The frame window consists of the active segments surrounding the client 
area, including the title bar, menu bar, system box, maximize and minimize 
boxes, and the frame border used for sizing the window. 

The call to the create function has the form 


WinCreateStdWindow(hParent, style, &ctrlbits, szClassname, 
szTitle, clientstyle, resource, id, &hClient); 


where 
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hParent 


style 


& ctribits 


szClassname 


szTitle 


clientstyle 


resource 


The handle of the parent to this window. The window is 
constrained to move about only within the boundaries of 
its parent. Here we will say that the window is the child 
of HWND_DESKTOP, a window filling the entire 
screen. 


Generally main windows are set to the style 
WS_VISIBLE. Child windows are set to style bits such 
as FS_BORDER, and made visible in a separate 
command controlling their size and position. There are 
also a number of other FS_ control bits that have iden- 
tical functions to the FCF_ control bits described below, 
which are present only for evolutionary reasons. 


This is a pointer to a 32-bit word containing bits 
describing the type of border, title bar, menu, min-max 
arrow boxes, and system menu box, as well as whether 
the program has an icon to display. 


This is the string containing the name of the window 
class. It is this name that determines the address of the 
window procedure that is to receive the messages. 


This is the title to be placed in the window title bar. If 
the style bits include FCF_TASKLIST, the program’s 
filename is placed in the title bar and this text appended 
to it. 


The style bits for the client window inside the frame 
window are usually just WS_VISIBLE. 


If this value is NULL then any menu information is to 
be found in the program file. Otherwise this is a handle 
to a module that contains these definitions. 


This must be a non-zero frame window identifier. If you 
create a main or child window that has an icon or menu 
associated with it, it is this value that must be used in 
defining that menu and icon in the resource file. Then, 
when the window is created, these objects are automat- 
ically loaded. 
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& hClient The handle to the client window is returned in this argu- 


ment. 


The example below illustrates how to set the FCF_ bits and open a 
standard window. 


flCreate = FCF _MINMAX | FCF SIZEBORDER | FCF SYSMENU | 
FCF TITLEBAR | FCF _SHELLPOSITION | FCF_ICON; 


/*create the window */ 

hFrame = WinCreateStdWindow( 
HWND DESKTOP, /*as child of the desktop window*/ 
WS VISIBLE | FS_ICON , 


&f1Create, /*control data bits * ff 
(PSZ)szClassName, /*this name refers to class*/ 
(PSZ)szMessage, /*title across top bar a f 
wS VISIBLE, /*''main'' window visible a 
NULL, /*“menu is in resource file “/ 
HELLOICON, /*icon identifier */ 
&hWnd) ; /*client area handle ae 


The long word flCreate contains a number of option bits to select the 
style of the window to be displayed. The bits we have chosen above are a 
reasonable default set. The complete set of options bits includes: 


FCF_TITLEBAR The window has a title bar. 
FCF_SYSMENU The window has the left corner system 
menu box. 

FCF_MENU The window has menus. 

FCF_SIZEBORDER The sizing border is to be shown so the 
window’s size and shape can be manipu- 
lated. 

FCF_MINBUTTON The window should display the down-arrow 


minimize button. 


FCF_MAXBUTTON The window should display the up-arrow 
maximize button. 
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FCF_MINMAX 


FCF_VERTSCROLL 


FCF_HORZSCROLL 


FCF_DLGBORDER 


FCF_BORDER 


FCF_SHELLPOSITION 


FCF_TASKLIST 


FCF_NOBYTEALIGN 


FCF_NOMOVEWITHOWNER 


FCF_ICON 
FCF_ACCELTABLE 


FCF_SYSMODAL 


FCF_SCREENALIGN 
FCF_MOUSEALIGN 


The window should have both minimize and 
maximize buttons. 


The window should have a_ vertical 
scrollbar. 


The window should have a_ horizontal 
scrollbar. 


The window should have the dialog box 
style border. 


The window should have a single line 
border. 


The window should be positionable on the 
PM shell display. This bit is required. 


The name of the main window program 
should be added to the task box list. 


SOSSOOOSOSOOOOHSOOSE 


Do not align windows on byte boundaries of \” 
the display. 


@< 


Do not move the child window with its ‘o, 


WY 


The window has an icon. &) 


owner. 


There is an accelerator table of keystrokes (__ 
to be loaded. | 
YY 


The window is modal: no other window can ‘o 
be active while it is active. : 

ww 
Ww 
Align the mouse cursor on byte boundaries. (_) 


Align child windows on byte boundaries. 


PM is very particular that you only define the bits that describe features you \_Y 
actually have in this program. For example, do not specify FCF_MENU if iJ 
you have no menus or FCF_ICON if you do not specify the name of an icon | 


ed 
WY 
ye 
Ww 
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file in your resource file. In fact, such programs will compile and link prop- 
erly but will ““mysteriously” refuse to run. 

As we noted, the class name we selected when we registered the window 
class is used as the third argument and is the only way that OS/2 can tell 
which window procedure is to receive the messages for that window. The 
text in szMessage is “Hello World” and becomes the name in the title bar 
across the top of the window. 

This call returns the handle to the window frame in hFrame and the 
handle to the window in hWnd. 


Loop Getting Messages until Quit Is Posted 


The two calls below get messages and dispatch them. If WinGetMsg returns 
NULL, this is equivalent to the WM_QUIT message (which has a NULL 
value) and the while loop terminates. 


/*get messages from the input queue and dispatch them */ 
while ( WinGetMsg( hAB, (PQMSG)&qmsg, (HWND)NULL, 0,0) ) 
begin 
WinDispatchMsg(hAB, (PQMSG)&qmsqg) ; 
end 


Terminate the Program 


The three statements below destroy the frame window and the message 
queue and terminate the program. When the frame window is ordered 
closed, it automatically sends close messages to its child window: the client 
window, so all windows are destroyed by this command. 


a 
x 


/* once the program is over, Z 
/* destroy the window and message queue “/ 
WinDestroyWindow(hFrame) ; 

WinDestroyMsgQueue(hmqHel lo) ; 

WinTerminate (hAB); /* the TERMINATOR!!! 
end 


ale 
nx / 
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THE WINDOW PROCEDURE 


Obviously, the real work of the program is not done in the main function, 
but in the HelloWndProc window procedure. This function receives all the 
messages sent to the window, and either acts on them or passes them on to 
the function WinDefWindowProc, which performs the default action for 


that message. 

In the window procedure shown in Figure 5-1 we check the value of 
message in a switch statement and then either execute the paint routine or 
pass the message on to the default window procedure. Obviously, in a more 
versatile program, we might interpret quite a number of messages in this 
switch statement. 

The bulk of this routine’s activity is in the WM_PAINT case. Here we 
see the WinBeginPaint and WinEndPaint calls bracketing code that deter- 
mines the rectangle size and where to write the string on the screen. 


PRESENTATION SPACES 


When WinBeginPaint is called, it returns a handle to a Presentation Space. 
A Presentation Space is an internal table of drawing attributes such as 
color, background, line type, font, and so forth that can be associated with 
any device on which you can draw graphics. The Presentation Manager 
defines three levels of Presentation Spaces: 


1. A cached micro PS 
2. A micro PS 
3. A normal PS 


The cached micro PS is used most commonly for simple drawing oper- 
ations. This PS table exists within the Presentation Manager and is created 
each time you need it, with default attributes assigned. It is the fastest one 
to create and use for simple drawing operations, but it does not remember 
attributes from one use to the next. 
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/* The window procedure receives messages and acts on them 
Or passes them on for default processing. Minimally, it 
must respond to WM PAINT, and may respond to WM CREATE 
and WM CLOSE */ 

fT Ten en ne RaDn memos BE Ee ter en aR MeN OMe CE enn aN TT ICDS TN De TU hes A PueOS DEACON 2a 

MRESULT FAR PASCAL HelloWndProc(HWND hWnd, USHORT msg, 

MPARAM mp1, MPARAM mp2) 


begin 
HPS HPS: /*“handle to presentation space “*/ 
RECTL res /*rectangle definition structure*/ 
Switch (msg) /*interpret messages i 
begin 


case WM PAINT: 
hPS = WinBeginPaint(hWnd, (HPS)NULL, (PWRECT)NULL); 


/*get current window dimensions*/ 
WinQueryWindowRect (hWnd, &rc); 


WinFillRect(h 
rc.xLeft = 50 
rc.yBottom = 50; 
rc.ytoo = 100; 
re.xRight = 150; 
WinDrawText(hPS, strlen('‘'Hi there!''), "Hi there!"', 

ére; CLR BLUE, CLR BLACK, DT LEFT); 


PS, &rc, CLR BLACK); /*fill it with black*/ 
; /"write at (50,50) */ 


WinEndPaint(hPS) ; /*end painting routine*/ 
break; 
default: 
return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
break; 


end /*switch*/ 


return((MPARAM)OL) ; 
end 


Figure 5-1. The Hellojl Window Procedure 
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The micro PS must be created each time you need it, and can remember , 
any set of attributes such as color, line type, etc., that you might need to 


®Oeoe 


C 


keep constant from one paint invocation to another. 

The normal PS allows you to keep a record of your graphics calls in a \) 
graphics segment associated with the PS memory and then play back these 
commands quickly when repainting is required. You can also edit and 

modify these graphics segments easily. In addition, the normal PS is the only Y 

PS that can be associated with more than one device. You can “detach” the \_/ 

normal PS from one device and reattach it to another device and have the Ly 
stored graphics segment information played back on this new device. | 

, 

‘? 

LU 


WinBeginPaint returns the handle to a micro presentation space, hPS. Then WY 


THE PAINT ROUTINE 


the function WinQueryWindowRect returns the size and position of the (| 
window in the RECTL structure re. This will always be a structure in which | 

the xLeft and yBottom values are zero, and the xRight and yTop values pt 
contain the window dimensions. In this case, however, we do not need to ever \’ 
look at these values, but simply pass them on to the WinFillRect function, (_) 
which clears the screen to black. All of the major colors are defined as con-¢ \ 
stants having the prefix CLR_. In this case the background is filled with ped 
CLR_BLACK. | 


Ending the Paint Routine 


6©@0¢ 


The WinEndPaint function simply releases the cached micro presentation, 


( 


space, completing the paint routine. This also completes the window proce- 


dure, since the routine exits after completing this function. The 
WinBeginPaint - WinEndPaint calls often are used to bracket a paint\v 


routine, since they allocate and deallocate a presentation space. The com- 


( 


plete call is 
WinBeginPaint(hWnd, hPS, &rect); 
where 


hWnd is the handle to the current window. 
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hPS can be NULL if you want a PS allocated, or can be the handle 
to a current PS if one already exists. 


& rect returns the rectangle boundary of the region of the window that 
must be updated. 


The WinEndPaint call tells PM that the screen region requiring update is 
now valid, and either releases the allocated micro PS or restores the existing 
PS to its state prior to the WinBeginPaint call. 


THE DISPLAYED WINDOW 


Once the program is compiled and linked, running it will give the display 
shown in Figure 5-2. The parts of the window are as follows 

The system box is the box containing the hollow dash in the upper left 
corner. If you click on this box, you will get a small menu containing the 
options shown in Figure 5-3. Clicking on any of these options causes that 
window to be maximized to full screen, minimized to an icon, or moved to a 
new location determined by moving the mouse and clicking at the new 
location. Clicking on Close causes the window to be closed. You can also 
close down any PM program without waiting for a menu by double clicking 
the mouse on the system box. | 

The title bar contains the current program title or other information. If 
you position the mouse pointer inside the title bar and press and hold the left 
mouse button, you can move the window to a new position determined by the 
position of the movable outline when you raise your finger from mouse 
button 1. This is called dragging the mouse and indicates that you are drag- 
ging the figure as well. 

The minimize box contains the down-arrow. If you click on it the window 
shrinks to an icon in the lower left corner of the screen. 

The maximize box contains the up-arrow. If you click on it the window 
will expand to full screen, and the minimize box will change to an up-arrow 
plus a down-arrow. If you click on this box, the window will shrink back to 
its previous size. You can also maximize the window by double clicking on 
the title bar, and reduce it to partial screen size by double clicking on the 
title bar when the window is maximized. 
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Hello World 





Figure 5-2. The HELLOJ1 program display 
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The command bar is the bar just below the title bar. It generally contains 
a list of top-level commands. When you click on the menu item, a drop-down 
list of commands appears. Since we haven’t put any command detection in WY 
our first PM program, none of the commands that might appear in this (> 


WY 


placing the mouse pointer on the frame. Here it will change to a double- VY 


menu will do anything. 
The frame can be dragged to change the window’s size and shape by 


headed arrow. Holding down the left mouse button and moving the mouse (__ 
allows you to move that side of the window frame to a new position, making ¢ » 
the window larger or smaller. Dragging the mouse after selecting a corner of 

the frame allows you to move two sides at once. | 


@ < 


FILES USED IN COMPILING A PM PROGRAM 


The following files figure in preparing a PM program. 


C The source code files 
MAK The MAKE file 
-H The include file(s) 
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Figure 


L 
.DEF 
“RC 
CO 
-DLG 
-OBJ 
EXE 
-RES 
-~DLL 
-LIB 
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Alt+F5 






Restore 














Move Alt+F7 
Size Alt+F8 
Maximize Alt+F9 
Minimize Alt+F10 


Close Alt+F5 
Task Manager Ctrl+Esc 


5-3. The System Box Menu 





The Link file list 

The definitions file 

The Resource file 

The icon image file 

The Dialog Box file(s) 

The compiled object file before linking 

The executable program 

The resource file compiled by RC or the dialog box editor 
A dynamic link library module to be linked at run time 

A library module to be linked to your program at link time 


In this first program, we will not have any dialog boxes, so we can delay dis- 
cussing the .DLG file, but we will need to have one of each of the other files. 


The Icon File 


The ICONEDIT program can be used to prepare a 32 x 32-pixel icon 


pattern to represent the program when its window is minimized to an icon. 
For this first example, we will make an icon file that simply has “‘Hi!” in the 


middle of the icon area as show in Figure 5-4. 


The Include File 


In this file we will define the one constant that we will use in this program: 
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Icon Editor - HELLOJ1.1ICO 
File Edit Qptions Palette Device Pen Size Help 


Figure Type: ICON 
Device: Independent 
Size: 64 x 64 
Hotspot: 32 x 32 
Pen Location: 7 x 63 


Hil 
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Figure 5-4. The ICONEDIT program display. The large square can be operated \/ 
on pixel by pixel using the mouse, and the small icon area shows the \) 
final icon at normal viewing size. 

WY 

#define HELLOWIND 1 wy 

We use this constant to refer to the frame window id in both the program (_) 

and the resource files to define the window that the icon will be associated , 

with. 


The Definition File 


&@0@¢ 


This file is exactly like the one we prepared for the TIMER program, except’ 
for the EXPORTS statement. 


( 


NAME HELLOJ1 WINDOWAP | 
DESCRIPTION ‘PM Hello Program: 
STUB 'OS2STUB.EXE' 


CODE MOVEABLE 
DATA MOVEABLE MULTIPLE 


SSCOSOSCOOE 


AAAba para bDAbAAAAEAI III riid: 
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HEAPSIZE 1024 

STACKSIZE 4096 

EXPORTS 
HelloWndProc @1 


The EXPORTS statement is required for all PM programs compiled with 
/AL or /AS, and must contain a list of all window procedures that are to be 
called from OS/2. In this first program, we have only the one window proce- 
dure HelloWndProc. Each of these procedure names must be followed by a 
commercial sign ((@) and an integer. These integers must each have dif- 
ferent values: they usually start at | and each additional window procedure 
name simply has the next largest integer for its id number. 

However, while we illlustrate the EXPORTS statement here for com- 
pleteness, if you compile with the /A/fu switches, this statement is unneces- 
sary as the external references are provided automatically by the compiler. 


The Resource File 


The resource file contains definitions for icons, menus, accelerator keys that 
act as menu items, and string tables, such as Help files might use. In this 
example, our resource file contains only the name of the icon file: 


we Je wb = al. Ww wb Wb A 
fPSER UE BSE Resource file For PEL Le ie eer es aa ree ae eet 


#include ‘‘hellojl.h'' 


POINTER HELLOWIND hellojl.ico 


The Make File 


To create a PM program, you must compile and link as usual, and then you 
must run RC, the resource compiler. The overall make file, then, must indi- 
cate these dependencies, and as before, the final module is listed first fol- 
lowed by the dependent modules. 
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HHH Make file for HELLOJI###### HAAR HAHA AHH 
hellojl.exe: hellojl.obj hellojl.rc hellojl.h 
link @hellojl.1; 
rc helloji.rc 


hellojl.obj: hellojl.c 
cl /c /Alfu /W2 /G2sc /0s /Zpe hellojl.c 


The Link File 


600600000066 


The link file lists the actual modules and libraries to be linked. These are as \” 


follows: WwW 
hellojl.obj /A:16 /NOD VW 
He On eee Ww 
hellojl.map 
os2.1libt YY 
llibcemt.1ib we, 
hellojl.def 

/ 


Note that we will habitually compile our programs using the large memory VU 
model /Alfu and link them using the multithread library LLIBCMT.LIB. 
The /NOD switch tells the linker not to look in the default C libraries for Y 
the library functions, but instead to look only in the specified libraries. The \_) 
/A:16 switch tells the linker to align segments on 16-byte boundaries, which CU) 
again is required for OS/2. | 
We will assume that the environment variable INCLUDE is set to point Y 


to the multithread include files: a, 
set INCLUDE=c:\INCLUDE\MT;c:\INCLUDE; WV 
Ww 
THE COMPLETE HELLOJ1 PROGRAM CODE ad 
a, 


In the complete program we show below, we illustrate the complete window¢ \ 
procedure in Figure 5-1 and the main program that creates the window in. 

for the main program shown below. Since the main program remains the 
same throughout all further examples, we will seldom show it again com-\ 
pletely, but will concentrate on the window and graphics functions. 
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/®*KEEKEE Basic Presentation Manager Prototype Program ***/ 
/* Displays a blue ''Hello World'' on a black background */ 
LEER SS PAL eee RRR E I BSN Ie RE ROR TE TERE PS TS PRA AL TOD INNES ICA GE TTS ON ICTE RS TORN Ty 
Oy#define INCL PM 
#include <os2.h> 
~ /#include <cdefs.h> 
O)#include <string.h> 
ax#include "hellojl.h' 


O)MRESULT FAR PASCAL HelloWndProc( HWND, USHORT, 
a MPARAM, MPARAM ) ; 


[EBERBEBABAR NE DM NAD BIS RIA WE NILA TO TS NRE UTA IRM Ie MRC 
O) pecccccnci Maion Functio RRRARRAAREAA EEK A KK 
@/* The main() function in a PM program registers the class 

of all windows and creates the main window. Then it gets 
and dispatches messages to that window until a WM QUIT 
) message is received, and closes down. a 


ah J oe oe oe I I I I I 
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void cdecl main () /*C main routine*/ 


begin 
QMSG qmsg; /*defining a message queue */ 
HAB hAB ; /“handle to anchor block “*/ 
HMQ hmqHel lo; /*handle to message queue */ 
HWND hWnd; /*client area window handle*/ 
HWND hFrame; /*frame window handle a 
ULONG f1Create; /*window create flag bits */ 


hAB = WinInitialize (NULL); /*init and get anchor handle*/ 
hmqHello = 
WinCreateMsgQueue(hAB, 0); /*creat msg queue*/ 


500000009 


OY/*register the Window class*/ 

mWinRegisterClass (hAB, /*handle to anchor block */ 
| (PCH)''Hello., /*name of window class a 
(PFNWP)HelloWndProc, /*address of window procedure*/ 
CS _SIZEREDRAW |CS SYNCPAINT, /*use these flags mf 
he ae /*“number of ''extra bytes */ 


flCreate = FCF_MINMAX | FCF _SIZEBORDER | FCF SYSMENU 


oo 
a 
m 
am | FCF TITLEBAR | FCF SHELLPOSITION | FCF ICON ; 
o 
om, 
oJ 
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/*create the window */ 
hFrame = 
WinCreateStdWindow( 
HWND DESKTOP, /*as child of the desktop window*/ 
WS VISIBLE , | 
&f Create, /*‘control data bits 
(PSZ)'"'Hello'', /*this name refers to class*/ 
(PSZ)''Hello World'', /*title across top bar*/— 
wS VISIBLE, /*''main''window visible ny 


©0000 6 
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WV 
NULL, /*menu is in resource File"/@® 
HELLOWIND, /*id of ICON in RC file “*/ 
&hWnd) ; /*client area handle * Fe 
/*“get messages from the input queue and dispatch them “*/ | 
while ( WinGetMsg( hAB, (PQMSG)&qmsg, (HWND)NULL, 0,0) ) “~/ 
begin WJ 
WinDispatchMsg(hAB, (PQMSG)&qmsqg) ; 
end Y 
U y ad 
/* once the program is over, a 3 
/* destroy the window and message queue */ Dud 
WinDestroyWindow(hFrame) ; WY 
WinDestroyMsgQueue(hmqHel lo) ; Cy 
WinTerminate (hAB); /* the TERMINATOR!!! */ 
end VY 
) 
CONCLUSIONS = 
VY 
Our first PM program certainly seems more complicated than the simpl@ 


two- or three-line “Hello World” program that students of C are first 
shown. However, by having set up all of these functions we are now in 
position to add any number of complex features with a minimum of effort 
Further, we should certainly note that while the original C example printeq_) 
its message and then exited, this example maintains a window and an icon at 
all times, and keeps the window display up to date, no matter how many 
other programs are running or might overlap it. The next step in our investi 
gation is adding menu commands to the program, which follows in the nex(_) 
chapter. 


Sees 





6 Adding Menu Commands 
to Your Program 


AAALILALTIL IIT 


We have just seen that putting a movable, adjustable window on the screen 
©) is not terribly difficult and that drawing text is quite simple. However, a real 
>» program should be able to accept commands from the user and carry out 
> useful work. To demonstrate a truly useful concept, we will design our first 

menu-driven program to change the “Hi there” text depending on the 
) command selected. 


J 


© THE MENU FOR HELLOVJ2 


J 


.~ in our first example, we will design a program that has a two-item menu 
that drops down from the ““Commands” menu and displays the commands 


Commands 


Foogie 
Moogie 


LRAAL, 





om We will write a program that will display the message “Foogie” if that 
command is selected from the menu, and “‘Moogie”’ if the other command is 

~_ selected from the menu. We will further add code to exit from the program 

©) if the function key F3 is depressed. 

o@, In Presentation Manager programs, the text of menus and the commands 

they send can be stored in the resource or .RC file. The messages are just 


79 
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text enclosed in quotes and the commands are simply small integers. These, 
integers are usually defined as constants and put in the include file: 


#def ine HELLOWIND 1 

#def ine HELLOCMD 101 
#def ine HELLOFOO 102 
#def ine HELLOMOO 103 


Then the resource file can deal with these commands symbolically using the 
MENU directive. For this program, the resource file will contain: 


#include ‘‘helloj2.h" 
POINTER HELLOWIND helloj2.ico 


MENU HELLOWIND PRELOAD 
BEGIN 
SUBMENU ‘'Commands', | HELLOCMD 
BEGIN 
MENUITEM ''Foogie’', HELLOFOO 
MENUITEM ''Moogie’, HELLOMOO 
END 


8000860000000 0O08 OE 


END 


The meaning of this is very simple: the text following the SUBMENU direc-(_) 
tive will appear on the menu bar, and the text of the MENUITEMs will 
appear when you click the mouse on the menu bar text. Once the menu has 
appeared, you can click on any of the menu items and the message having 
that number will be sent to the program as a WM_COMMAND message. LY 

Note that the constant HELLOWIND is the frame window identifier,, 
and it must be associated with both the icon and the menu to be loaded with 
this window. Similarly, if you create a number of windows and subwindows, 
each having menus (or icons), the frame window identifiers for each of them\__ 
must be unique and the same as_ those used when each 
WinCreateStdWindow call is made. 

You can nest the SUBMENU commands to any depth, so that a menu 
item may bring up more menus as desired. 
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M MENU HELLOMENU PRELOAD 


BEGIN 
SUBMENU ''Commands'', HELLOCMD 
on BEGIN 
MENUITEM ''command1'', COMMAND 1 
SUBMENU ''multicommand'', COMMANDMULT 
o BEGIN 
> MENUITEM ‘'command2'', COMMAND2 
m4 MENUITEM ''command3'', COMMAND3 
| END 
m, END 


END 


wm Each submenu and menu item must have a constant associated with it 
although each constant need not be unique. 


vi 


Separators You can use the special menu item MIS_SEPARATOR to 
a draw a line between groups of menu items in a pull-down menu. 


SUBMENU ''multicommand'', COMMANDMULT 
BEGIN 
MENUITEM ‘'command2'', COMMAND2 
MENUITEM ''',NULL,MIS SEPARATOR 
MENUITEM ''command3'', COMMAND3 
END 

END 
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INTERPRETING MENU COMMANDS 
Oo 
When a_ user selects a command from a menu, the message 
WM_COMMAND is sent to that window with the lower 16 bits of the first 
parameter (mp1) containing the command constant listed alongside the 
menu. Inside the window procedure, we write a second switch statement to 
interpret the commands when WM_COMMAND is received. 


mmcase WM COMMAND: /*“interpret commands*/ 
switch(LOUSHORT (mp1) ) 
begin 
case HELLOFOO: /*change text to Foogie”*/ 


strcpy(mstring, Foogie’); 
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break; 
case HELLOMOO: /*change text to Moogie*/ 
strcpy(mstring, Moogie ); 
break; 
default: /*else do nothing | 
return(WinDefWindowProc(hWnd, message, mpl, mp2)); 
end 


©0000 00008 04 


WinIlnvalidateRect(hWnd, NULL, FALSE); /*force repaint 
break; 


, 


In this program, we use the macro LOUSHORT to obtain the value of the 
lower 311. LOUSHORT macro word of mp1. This macro is defined in 


WS 
os2def.h YS 
WwW 


and is automatically included when we define INCL_PM. 

This code simply copies the string “Foogie” into the string mstring if the 
message HELLOFOO is received and copies the string “Moogie” into the\__ 
string if HELLOMOO is received. Then it calls the function, 
WinInvalidateRect, which in turn forces the window to be repainted. The ~ 


arguments to this call are od 

WinlnvalidateRect(hWnd, &rect, scope); Y 

where = 

a, 

hWnd is the handle to the window to be repainted. re 

& rect is the pointer to the RECTL structure containing the region to) 
be invalidated or NULL if the whole window is invalid. | 

VS 

scope is TRUE if children of hWnd are to be included or FALSE '@ 
they are to be included only if the parent does not have the 

WS_CLIPCHILDREN style. ed 

WS 

INITIALIZING THE WINDOW bd 

\we 

In this example, we have substituted mstring for the message “Hi there” of | 


the previous example. We copy the correct string into mstring depending o 


Seeo 


o 

o 
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o 

Ov'rhe message. It is critical, therefore, that this variable be static since it must 

yetain this value from one call to the window procedure to the next. In addi- 
tion, we must initialize this string with some value when we first start up the 
window. You can do this by intercepting the WM_CREATE message and 
initializing the string: 


oY Static char mstring[ 80]; 
geo ttcn (message) /*interpret messages*/ 
begin 
case WM CREATE: 
a strcpy(mstring, ‘Hi there’); /*“initialize message*/ 
pd break; 


the WM_CREATE message is sent to the window procedure before the 

‘WinCreate... call returns, which is before the window is made visible. 
Therefore, you cannot draw anything at create time, but you can initialize 
vonstants needed for later drawing. 


om 
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-o™ 
Whenever any keyboard key is depressed, a WM_CHAR message is sent to 


che window having the input focus. When this happens, the upper word of 
(mp2 contains the scan code and the lower word the ASCII character code. 
Function keys, of course, do not have character codes, but their scan codes 

have been defined as VK__Fn code, where VK stands for “virtual key.” Here 

we use the macro SHORT2FROMMP to get at the upper word of the 
O message: 


Orkase WM CHAR: 
™ if (SHORT2FROMMP( mp2) == VK_F3) /* F3 causes WM QUIT*/ 
- begin 

WinPostMsg(hWnd, WM QUIT, OL, OL); /*terminate */ 
o end 
> break; 
e@mNote that we do not actually exit from the routine here, since this would 
gas the window active. Instead, we post the WM_QUIT message to the 
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window, so that the default window processing will close the window. The 
final running window is shown in Figure 6-1. 


[=| Hello World 


Commands 
Foogie 





Figure 6-1. The HELLOJ2 program display 
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The complete program text is shown below. The main program that sets up\_) 
the window differs from the main program at the end of Chapter 5 only in, 
that the style FCF_MENU is included in the flCreate flag. 


) 


¢ 


#define INCL PM 
#include <os2.h> 
#include <cdefs.h> 
#include <string.h> 
#include ‘‘helloj2.h- 


al. JL Wb I I J I I I I I I I I I 
al 
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/* The main() function in a PM program registers the class 
of all windows and creates the main window. Then it gets 
and dispatches messages to that window until a WM QUIT 
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we 


message is received, and closes down. = J 
i a 
void cdecl main () /*C main routine*/ 
begin 

QMSG qmsg; /*defining a message queue a 
HAB HAB ; /*handle to anchor block a 
HMQ hmqHel lo; /“handle to message queue */ 
HWND hWnd; /*client area window handle */ 
HWND hFrame; /*frame window handle * / 
ULONG f1Create; /*window create flag bits * f 


hAB = Winlnitialize (NULL);/*init and get anchor handle*/ 
hmqHello = WinCreateMsgQueue(hAB, 0); /*creat msg queue*/ 


AAAI ATT 


‘/*register the Window class*/ 


©) WinRegisterClass (hAB, /*handle to anchor block*/ 
>, 'Hello2'"', /*name of window class “*/ 
Hel loWndProc, /*address of window procedure*/ 

-) CS SIZEREDRAW |CS SYNCPAINT, /*use these flags  */ 
o 0) ; /*number of "extra bytes*/ 
@ kicreate = 
™ — FCF_TITLEBAR | FCF_MINMAX |FCF_SYSMENU | FCF MENU | 
a>, FCF SIZEBORDER | FCF BORDER | 

FCF SHELLPOSITION | FCF ICON; 
o 
@ /*create the window */ 

hFrame = 

fo~ 


)WinCreateStdWindow( 
HWND DESKTOP, /*as child of the desktop window*/ 
WS VISIBLE | FS_ICON, 


&f1lCreate, /*control data bits =f 
"Hello2'', /*this name refers to class*/ 
‘'Hello World'', /*title across top bar oy 

WS VISIBLE, /*''main''window visible gr 
NULL, /*menu is in resource file */ 
HELLOWIND, /*frame window id-you pick */ 
&hWnd) ; /*client area handle nf 
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/*get messages from the input queue and dispatch them 
while ( WinGetMsg( hAB, &qmsg, (HWND)NULL, 0, 0) ) 
begin 
WinDispatchMsg(hAB, &qmsg); 
end 


/*“once the program is over, 

destroy the window and message queue “/ 
WinDestroyWindow(hFrame) ; 
WinDestroyMsgQueue(hmqHel lo); 
WinTerminate (hAB); ie 
end 


wb wb wb be eI 
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the TERMINATOR!!! */ 


/* The window procedure receives messages and acts on them 
or passes them on for default processing. Minimally, it 
must respond to WM PAINT, and may respond to WM CREATE 
and WM CLOSE a 
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MRESULT FAR PASCAL HelloWndProc(HWND hWnd, USHORT msg, 

MPARAM mp1, MPARAM mp2) 


begin 
HPS hPS; /*handle to presentation space “*/ 
RECTL rcs /* rectangle definition structure*/ 


static char mstring[80]; 


switch (msg) /*interpret messages*/ 
begin 
case WM CREATE: 
strcpy(mstring, "Hi there’);  /*initialize message “*/ 


break; 
case WM COMMAND: /*jinterpret commands  “*/ 
switch(LOUSHORT (mp1) ) 
begin 
case HELLOFOO: /*change text to Foogie”/ 
strcpy(mstring, Foogie ); 
break; | 
case HELLOMOO: /*change text to Moogie*/ 


strcpy(mstring, Moogie  ); 
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break; 
default: /*else do nothing oe 
return(WinDefWindowProc(hWnd, msg, mp1, mp2)); 
end 
WinlnvalidateRect(hWnd, NULL, FALSE); /*force repaint */ 


break; 


case WM PAINT: 
hPS = WinBeginPaint(hWnd, (HPS)NULL, (PWRECT)NULL) ; 


/*get current window dimensions*/ 
WinQueryWindowRect (hWnd, &rc); 


WinFillRect(hPS, &rc,CLR BLACK); /*fill it with black*/ 
rc.xLeft = 50; /*write at (50,50)*/ 
rc.yBottom = 50; 
rc.ylop = 100; 
re.xRight = 150; 
WinDrawText(hPS, strlen(mstring), mstring, &rc, 

CLR BLUE, CLR BLACK, DT LEFT); 
WinEndPaint(hPS) ; /*end painting routine*/ 
break; 


case WM CHAR: 
if (SHORT2FROMMP( mp2) == VK F3) /* F3 causes WM QUIT */ 
begin 
WinPostMsg(hWnd, WM QUIT, OL, OL); /*termimate 
end 
break; 


. 


default: /*pass on other messages*/ 
return( WinDefWindowProc( hWnd, msg, mp1, mp2)); 
break; 

end /*switch*/ 


return(0L); 
end 
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Disabling and Enabling Items 


In programs where you must have data present before you can perform oper- 
ations on it, you might find it useful to disable any menu items that cannot 
be used without data. This is done by sending the particular menu item an 
MM_SETITEMATTR message to set new item attributes. 

Now, a menu item is generally known by its value, but you can only send 
messages to windows. Therefore you must get the window handle of that 
menu item using the function WinWindowFromID. Further, since the 
window containing the menus is not the client window but the frame 
window, you need to get the handle to the frame window to start. This is 
done with the WinQuery Window function: 


hFrame = 
WinQuer yWindow(hWnd, 
QW PARENT, FALSE); /*get the frame handle*/ 


Then, you get the handle to the menu window by making the call 


hMenu = 
WinWindowFromID(hFrame, FID MENU); /*“get handle to menu*/ 
Changing the Menu Item Attributes 


The MM_SETITEMATTR message allows you to set any of the following 
menu attributes: 


MIA_CHECKED The menu item is checked. 
MIA_DISABLED The menu item is grayed and not selectable 
MIA_FRAMED The menu item is framed. 
MIA_NODISMISS If this item is true, the pull-down menu 


containing this item will not be hidden 
before sending the message to the window 
that this item has been selected. 
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a, | 
©) The two message parameters sent with this message have the following 


Pas format: 
@) WinSendMessage(hMenu, MM_SETITEMATTR, (itemval, submenus), 


) where 

©) itemval is the menu item to change. 

Cy submenus is TRUE if submenus are to be searched and FALSE if 
“ not. 

©) mask is the mask describing which bits are to be changed. 

oY attrib is the attributes to be changed. 


Note that to grey an item or disable it, you set the MIA_DISABLED bit, 
Cy and to enable the item you c/ear it. Thus, to disable an item you might write 


e hFrame = 
©) WinQueryWindow(hWnd, 
QW PARENT, FALSE); /*get the frame handle*/ 
hMenu = 


©) WinWindowFromlD(hFrame, FID MENU); /*get handle to menu */ 
m@) WinSendMsg(hMenu, MM_SETITEMATTR, /*disable menu J 
MPFROM2SHORT(HELLOFOO, TRUE), 

MPFROM2SHORT(MIA DISABLED, MIA DISABLED)); 


and to enable the item, 


WinSendMsg(hMenu, MM SETITEMATTR,  /*enable menu “ 
MPFROM2SHORT(HELLOFOO, TRUE), 
MPFROM2SHORT(MIA DISABLED, NULL) ); 


Similarly, to check the menu item, you could write 


WinSendMsg(hMenu, MM SETITEMATTR, /*check menu oe 
MPFROM2SHORT(HELLOFOO, TRUE), 
MPFROM2SHORT(MIA CHECKED, MIA CHECKED)); 
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ADDING MENU ITEMS DYNAMICALLY 


To add menu items to an existing menu bar, you must add a main menu 
item with an associated submenu and then add submenu items. To insert a 
main menu item on the title bar, you send the frame _ the 
MM_INSERTITEM message, where mp1 points toa MENUITEM struc- 
ture and mp2 contains a pointer to the text to be displayed. The 
MENUITEM structure has the form 


typedef struct MENUITEM 


begin 

SHORT iPosition; /*position in the menu, or MIT END*/ 
USHORT afStyle; /*style, usually MIS TEXT */ 
USHORT afAttribute; /*usually NULL */ 
USHORT id; /*id value sent when item is selected*/ 
HWND hwndSubMenu; /*“handle of submenu if 
ULONG hI tem; /*usually NULL ay 


end MENUITEM; 


Now, insert a main menu that has submenus, we must have the handle to 
the submenu in advance. We obtain it by using the WinCreateMenu call, 
which returns the handle to a menu that we place in this structure. Thus, to 
create a main menu called “User” we write 


MENUITEM mu; /*menu item structure 


hFrame = 
WinQueryWindow(hWnd, QW PARENT, FALSE); /*get frame*/ 

hMenu = 
WinWindowFromID(hFrame, FID MENU) ; /*get menu handle*/ 
mu. iPosition = MIT END; /*add at end * / 


mu.afStyle = MIS TEXT | MIS SUBMENU; /*set style a 
mu.afAttribute = NULL; 

mu.id = 110; /*command value */ 
mu.hwndSubMenu = 


WinCreateMenu(hFrame, NULL); /®ereate submenu */ 
mu.hltem = NULL; 
WinSendMsg(hMenu, MM _INSERTITEM, (MPARAM)&mu, 
(MPARAM)' User’); 
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Ait 


©) Now, to insert items in the submenu under the main menu item “User,” we 
em Simply get the structure back, and insert into its submenu 


WinSendMsg(hMenu, MM QUERYITEM, 
MPFROM2SHORT(110,TRUE) , (MPARAM ) Emu) ; 


O hSubMenu = mu.hwndSubMenu; /*get submenu handle*/ 
ay mu hwndSubMenu = NULL; /*no more submenus */ 

mu.id = 111; /*set new command = */ 
O)mu.iPosition = MIT_END; /*insert at end 4 
am mu.afStyle = MIS_TEXT; /*text style se 


mu.afAttribute = NULL; 
©) mu-hitem = NULL; 
S WinSendMsg(hSubMenu, MM_INSERTITEM, 


(MPARAM) &mu, 
oy (MPARAM)''Math'); /*insert ''Math'' ay 
™) WinSendMsg(hFrame, WM UPDATEFRAME , 
NULL, NULL); /*redraw frame my 
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USING THE KEYBOARD WITH PM PROGRAMS 


For people who are afraid of mice, it 1s possible to issue most commands 
directly from the keyboard. If you look at the main menu of most complete 
programs, you will discover that each item in the menu bar has one char- 
acter underlined. For example, the ICONEDIT program has the following 


command line: 
File Edit Options Color Open Size Exit 


You can access any of these commands by pressing and releasing the Alt 
key. The “File” item will be highlighted. Then, you can select any of the 
menus by simply pressing the highlighted character: F, E, O, C, P or X. The 
case of the character you press does not matter. When you do this, that 
menu will appear, again, with some character underlined. If you press “F” 
the File menu will appear: 


New 
Open 


Save Alt+F3 
Save As... 
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You can select an item from that menu by either moving the highlight bar 
down to the item with the cursor arrow keys, or by pressing the underlined 
character. For example, to save the current file, just press “S.’’ Thus, you 
can, in every case, select a menu item and execute it in three key strokes: 
here, “Alt,” “F,’ and “S.” 


SELECTING UNDERSCORED CHARACTERS 


The Resource compiler allows you to indicate the character that is to be 
underscored in your menu items and recognized by the keyboard command 


660,99 


processor by simply preceding the character with the character. 


MENU HELLOMENU PRELOAD 
BEGIN 
SUBMENU ''~Commands'', HELLOCMD 
BEGIN 
MENUITEM ''~Foogie, HELLOFOO 
MENUITEM ''~Moogie', HELLOMOO 
END 
END 


MENU ACCELERATORS 


PM also provides you the ability to use single keystrokes to select commonly 
used functions. For example, we have already seen how we can intercept the 
F3 function key asa WM_CHAR message to exit from a program. We can 
also define particular keystrokes, usually Alt and Ctrl combinations, as ones 
that will send the same command messages to the program as do the menu 
items themselves. This is done through a menu accelerator table. The fol- 
lowing accelerator table is made part of the Hello program by including it in 
the resource file: 


ACCELTABLE HELLOWIND PRELOAD 
BEGIN 
se!" | HELLOFOO, CHAR, ALT 
'm'', HELLOMOO, CHAR, ALT 
END 
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This table simply says that the keystroke Alt/f will send the message 
HELLOFOO to the current window, and that the keystroke Alt/m will send 
the message HELLOMOO to the current window. These will then be proc- 
essed in exactly the same way as if the commands had been selected from 


the menu. 


Virtual Keys 


You can also specify function keys, alone or combined with ALT, SHIFT, 
or CONTROL, for a number of additional accelerators. Instead of being of 
type CHAR, these are specified as of type VIRTUAL. Since the codes for 
these virtual key symbols are not known to the resource compiler, you must 
include the <os2.h> file in the resource file. 


#include <os2.h> 
#include ‘'helloj.h- 


ACCELTABLE HELLOLABL PRELOAD 


BEGIN 
'e!! = HELLOFOO, CHAR, ALT 
''m'', | HELLOMOO, CHAR, ALT 
f'! HELLOFOO, CHAR, CONTROL 


VK_F1, HELLOFOO, VIRTUALKEY 
VK_F1, HELLOFOO, VIRTUALKEY, SHIFT 
END 


Loading the Accelerator Table 


If you do not specify PRELOAD, the final step in using the accelerator 
table is loading the table when you open your main window. You must 
specify the style bit FCF_ACCELTABLE when you create the window: 


flCreate = 
FCF TITLEBAR | FCF MINMAX |FCF SYSMENU | FCF MENU | 
FCF ACCELTABLE | FCF SIZEBORDER | FCF BORDER | 
FCF SHELLPOSITION | FCF ICON; 


or you must load the table when you are ready to use it: 
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WinLoadAccelTable(hAB, NULL, 
HELLOACCEL) ; /*load the accelerators*/ 


where NULL indicates that the table is in your resource file, and 
HELLOWIND is the id number of the frame window, defined in the 
helloj3.h file: 


#def ine HELLOWIND 1 

#def ine HELLOCMD 101 
#def ine HELLOFOO 102 
#def ine HELLOMOO 103 


THE WM_CHAR MESSAGE 


We have already seen that the lower word of mp2 contains the “virtual key 
code” needed to recognize function keys. These virtual key codes have been 
defined by OS/2 to eliminate the conflicts inherent in different versions of 
PC keyboards. In the original PC, the scan codes for each key were simply 
their numerical position on the keyboard, with the 10 function keys taking 
positions along the left side of the keyboard. Since then at least three other 
versions of the PC keyboard have appeared from IBM alone, with additional 
versions from other manufacturers, some with numeric keypads, some with 
cursor keys, and some with neither. To insulate the user from these differ- 
ences the keyboard driver returns a series of “‘virtual’’ key codes whose 
numerical value has nothing to do with any series of scan codes, but is con- 
sistent for all keyboards. This is simply an example of the attempts of the 
PM designers to make the system completely device independent. 

In fact, the two message parameters contain a wealth of information that 
makes the identification of keys and their associated shift keys simple and 
unambiguous. Parameter one contains the following information: 


and parameter mp2 contains 


ascii char virtual code 


The flags have the following values 
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KC_CHAR 


KC_SCANCODE 


KC_VIRTUALKEY 
KC_KEYUP 


KC_PREVDOWN 


KC_DEADKEY 


KC_COMPOSITE 


KC_INVALIDCOMP 


KC_LONEKEY 


KC_SHIFT 


KC_ALT 
KC_CTRL 
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If set, this key has a valid character value in 
mp2. 


If set, this key has a valid scancode value in 
mpl. 


Indicates that the virtual key code is valid. 


If set, this is a key-up transition. Otherwise 
the key was pressed down. 


The key was previously down. Otherwise it 
was previously up. 


This is a “dead” key. Your program must 
display any desired character for this key 
without advancing the cursor. 


The character code is formed by combining 
this key with the previous dead key. 


The character code is not a valid composite 
with the previous dead key. 


Indicates if this key is pressed or released 
without any other key being pressed or 
released at the same time. 


A shift key is also down. 
An ALT key 1s also down. 


A control key is also down. 


The other values in these message parameters are 


repeat The number of times the key has been repeated. 


scancode The raw scan code for this key. You should always use the 


virtual key code instead. 


char The ASCII code for the character. This is zero for all control 
and function keys, as well as for the cursor keys. 
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virtual The virtual key code. This value is 0 if flags does not have 
KC_VIRTUALKEY set. 

The Virtual Keys 

The following virtual keys have been defined by PM. 
VK_BREAK VK_ESC VK_INSERT 
VK_BACKSPACE VK_SPACE VK_DELETE 
VK_TAB VK_PAGEUP VK_SCRLLOCK 
VK_BACKTAB VK_PAGEDOWN VK_NUMLOCK 
VK_NEWLINE VK_END VK_ENTER 
VK_SHIFT VK_HOME VK_SYSRQ 
VK_CTRL VK_LEFT VK_FI 
VK_ALT VK_UP VK_F2 
VK_ALTGRAF VK_RIGHT 
VK_PAUSE VK_ DOWN VK_F24 


VK_CAPSLOCK VK_PRINTSCRN 
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3: Using Dialog Boxes with 
the Presentation Manager 


The recommended way of entering and changing information in a program 
is using a dialog box. This is a pop-up box that allows the user to enter 
values, select options, and type in text. The shape and layout of these boxes 
can be edited graphically using the DLGBOX editor. 


TYPES OF DIALOG ITEMS 


There are several types of items that you can put in a dialog box for the user 
to select. Each of these is actually a little child window whose characteristics 
and messages have been preprogrammed to behave in standard ways. 


Push buttons A box with a word or two inside that can be selected 
with the mouse. Usually, these are used for selections 
such as “OK” or “Cancel.” 


Radio button One of a series of round buttons, labelled at the side. 
Only one of these buttons can be depressed at a time. 
PM defines radio buttons as those where selecting one 
button causes PM to unselect any other button of the 
group. Normal radio buttons require that your program 
do the selecting and unselecting. 
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Check boxes A series of square boxes that can be “checked” or 
“unchecked” to indicate selection of one or more options. 
They differ from radio buttons in that more than one can 
be checked at a time. 


Text box A box containing static text that cannot be edited. 
Edit box A box containing text that can be edited. 
List box A box containing a list of selections, such as filenames. 


Any item in the list can be selected. List boxes come 
with vertical scroll bars built in so the user can use the 
mouse to scroll through a large list. 


multiline edit boxes A box containing several lines of text that can be edited. 


Scroll bars Horizontal and vertical scroll bars can be used to scroll 
horizontally through wide text or vertically through 
many lines of text. Selecting the scroll bar position 
causes messages to be sent to the dialog box to redraw 
the contents. 


DESIGN OF THE CHGCOLOR PROGRAM 


We are going to write a program to display an empty window with red back- 
ground and the single item “CCommand” in its menu bar. When the menu is 
pulled down, the command “Dialog” appears. When “Dialog”’ is selected, a 
dialog box will pop up with three radio buttons, labelled “Red,” “Green,” 
and “Blue.’? Two push buttons, labelled ““OK” and “Cancel,” appear at the 
bottom as illustrated in Figure 8-1. 
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o Red 


o Blue 


o Green 
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. Figure 8-1. The design of the dialog box 

The button representing the current screen color will be highlighted. When a 
™) button is selected and the “OK” push button is selected, the dialog box dis- 
™) appears, and the screen changes to that color. If “Cancel” is depressed, the 
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ma, 


} 


a CREATING A DIALOG BOX 


dialog disappears and no color change occurs. 


oO The first thing to do in creating a dialog box is to design its layout. You do 
©) this by running the DLGBOX program and arranging the various elements 
mon the screen in a logical order for your purposes. When you start 
DLGBOX, you are presented with the menu 
> File Include Edit Control Options Exit 
a, Always start by selecting Edit, and “New Dialog” from the Edit menu. You 
will immediately be asked for the Dialog Box identifier. This can be a 
~ number (the default is 256) or it can be a symbolic variable. Enter the sym- 
©) bolic name COLORDIALOG for the box, and DLGBOX will assign it the 
™» first unused value starting at 256. A square box will appear on the screen 
that you can move around by pointing the mouse inside the box, holding the 
left button down, and moving the mouse to drag the box to a new position. 
©) You can also change the box’s shape by dragging any side or corner to a new 
™ position. 
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Then, to put controls inside the box, select them from the “Control” 
menu. Let us select “Radio Button” from this list. A small box will appear 
that you can move within your dialog box. When you have moved it to the— 
right position, press the left mouse button and a dialog will appear, asking 
you for the Button Control Style. The choices will appear as shown in) 
Figure 8-2 Select “Auto Radio Button” and give the button text a message 
such as “Red” and an identifier such as BUTN_RED. An auto radio button 
or check box will darken when the user clicks on it and any other radiowW 
button will “pop out” and become light again. You should always use the__ 
auto feature of these dialog elements. 7 

Push buttons allow you to check the default feature for one of them sow 
that the default “OK” or “Cancel” is the one that is automatically selected\/ 
if you just press Enter when the dialog box is active. In this case, select the) 
default box for OK. Continue doing this until you have arranged a box as 
shown in Figure 8-3, where the elements of the box have the following sym- 


bolic identifiers: Y 
COLORDIALOG The dialog box as a whole. ~~ 
BUTN_RED The button labelled “Red.” ead 
BUTN_BLUE The button labelled “Blue.” @ 
BUTN_GREEN The button labelled “Green.” & 
ID_OK The OK push button. ID_OK  should_> 

always be given the numeric value of 1. 
ID_CANCEL The Cancel push button. [D_-CANCE 

should always be given the numeric value of 

2. 


Then select “Save” from the file menu to save the dialog box. You will be 
asked for the name of the box and the name of the include file in which you” 
wish to store the symbolic values you just generated. We will save the dialog_V 
box as COLOR.DLG and the include file as CDIALOG.H. 

After you have selected options and positioned a dialog item on the 
screen, you can still change its style or even its button type by selecting that 
dialog element with the mouse, and then selecting “Styles” from the “Edit’\V 
menu. The same menu will pop up for you to select options. 
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File Include Edit Control Qptions Help 
Mode: Work 


Button Control Styles 


Choose button style and type button text 
and ID value. 


Types Options 

© Push Button ("] Default 

© Check Box (7 Help 

© Auto Check Box CJ SYSCOMMAND 


© Radio Button CI Ne Boarder 
@ Auto Radio Button (CJ No Focus 
© 3 State 

© Auto 3 State 

© Ng Cursor Select 

© User Button 


Button text. (effenene! (23,90) 


(cx, cy]....... : (30,12) 
Relative to: Dialog Box 
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Figure 8-2. Selection of button attributes in the DLGBOX program 
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o THE RES AND DLG FILES 


oy The DLGBOX editor creates two files having the root name you select when 
©) you save the file: COLOR.DLG and COLOR.RES. The RES file is the 
™» resource-compiled version of the DLG file and may be combined directly 
with the EXE file using the RC compiler. The DLG file contains the same 
information in an ASCII format and can be copied into a general resource 
© file for that program. If you look at the .DLG file, you will find that it con- 
™) tains the coordinates and characteristics of the elements of the dialog box: 


OY DLGINCLUDE 1 ''CDIALOG.H'! 


DLGTEMPLATE COLORDIALOG LOADONCALL MOVEABLE DISCARDABLE 
) BEGIN 
a, DIALOG '"', COLORDIALOG, 94, 85, 79, 125, FS NOBYTEALIGN | 
FS DLGBORDER | WS VISIBLE | WS CLIPSIBLINGS | 
WS SAVEBITS | 
BEGIN 
CONTROL ‘Blue’, BUTN BLUE, 23, 67, 40, 14, WC BUTTON, 
BS AUTORADIOBUTTON | WS GROUP | WS TABSTOP | 
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Dialog Box Editor: [CHGCOLOR.RESs] [CLRDEFS.H] 
File Include Edit eiiitim Options Help 
~ Push Button Mode: Work 
Check Box 
Radio Button 
Horz. Scroll 
Vert. Scroll 
List Box 
Edit 
Group Box 
Text O Red 
Erame 
Rectangle 
Icon © Blue 
Bitmap 
Combo Box 
Multiple LE © Green 


User Defined 
Cancel 


Selected Item Status 
(X,y]....cceee003 (154,37) 
(cx, cy)....... : (79,125) 
Relative to: Window 
Control : Dialog Box 
ID Value: COLORDIALO) & 
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Figure 8-3. The CHGCOLOR dialog box design. Note the default box around the 
OK button. | 


WS VISIBLE 
CONTROL ‘Green’, BUTN GREEN, 24, 45, 42, 12, WC BUTTON, 
BS AUTORADIOBUTTON | WS TABSTOP | WS VISIBLE 
CONTROL ''Red'', BUTN RED, 23, 90, 30, 12, WC BUTTON, 
BS AUTORADIOBUTTON | WS TABSTOP | WS VISIBLE 
CONTROL ''OK'', ID OK, 10, 20, 24, 14, WC BUTTON, 
BS PUSHBUTTON | WS GROUP | WS TABSTOP | 
WS VISIBLE 
CONTROL ''Cancel'', ID CANCEL, 39, 20, 34, 14, WC BUTTON, 
BS PUSHBUTTON | WS _TABSTOP | WS VISIBLE 
END 
END 


There are two ways of getting this information into your program: b 
putting it in your resource file and by including it in your resource file. T 
include it in your resource file, simply add the statement 


rcinclude color.dlg 
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to your resource file. It turns out, however, that if you have several dialog 
boxes in your program that all refer to the same include file for the defi- 
nitions of their symbolic values, it is preferable to simply copy the text from 
the .DLG file into your resource file using your favorite text editor. If you 
include several .DLG files that start with the same DLGINCLUDE state- 
ment, the resource compiler will produce an .EXE file that cannot be loaded 
because of these apparent duplicate definitions. You can, however, put a 
number of dialogs in a single DLG and RES file, and selct any one of them 
for later editing as your program develops. 


DIALOG BOX DESIGN 


A dialog box allows you to select any of a number of options, including 
entering text and values. The user should be able to make a number of 
changes to his work and still be able to inspect the values in the box before 
closing the box and making the values permanent. Therefore, it is customary 
that all such boxes have a pair of push buttons marked “OK” and “Cancel.” 
If “OK” is pushed then the currently selected values become permanent, 
and if “Cancel” is selected, the previous values remain in force. To be con- 
sistent with standard usage of dialog boxes, the messages DID_OK and 
DID_CANCEL have been defined as having the values | and 2, respec- 
tively, in pmwin.h. 


STARTING A DIALOG BOX 


A dialog box procedure is really just a special kind of window procedure. It 
must be declared by name in an EXPORTS list in the .DEF file (unless you 
compile with /Alfu), but does not need to have its class registered, since all 
dialog box procedures are of the same window class. You call a dialog box 
with the call 


WinDIgBox(HWND DESKTOP, hWnd, Dlgproc, resid, digid, 
&params) ; 


where 


VW 
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Y 
HWND_DESKTOP is the parent window handle of the dialog’ ) 


window. Making the desktop the parent is recom- 
mended so the box can appear anywhere on the 


screen. WJ 
hWnd is the handle of the owner window. This is usually 
the calling window. oo, 
Digproc is the dialog box’s window procedure address. ‘J 
resid is the resource file handle containing the template 


for the dialog box. If this is linked into the) 
program’s EXE file, as is usually the case, thig > 
handle must be NULL. 


WY 
digid The id value of the dialog box. This is the sym; 
bolic name you chose when you first created the 

dialog box using DLGBOX. WY 

& params This can be a pointer to a data word or structure 


that you want to pass to the dialog box as an arguX/ 


ment. WY 
Dialog boxes called in this fashion are said to be modal and prevent yot_L 
from accessing any other window until this dialog is closed. You can als¢ 
use the WinLoadDlg call along with WinShowWindow to create a modeless 
dialog box that will allow processing in other windows simultaneously. 


THE DIALOG WINDOW PROCEDURE 


6@e< 


The dialog box window procedure is much like any other window procedure 


( 


messages are received and interpreted. However, since the dialog box is 
really a special class of window and all of the dialog features are actually 
little child windows, the messages that are received are somewhat i] .chila/ 
windows different. 

The first message the dialog box receives is a WM_INITDLG message 
and it is intended to be used to set up the initial status of the box when it 
appears. Dialog boxes should always represent the current status of variables 
in the program rather than some arbitrary set of default values. Thus, a\_> 
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initialization time, you might set the text of certain messages and check par- 
apticular boxes and “push” a particular radio button. 


on 
WRITING THE CHGCOLOR PROGRAM USING A 
_~DIALOG BOX 


We will now write an example that will have one menu item “Dialog.” We 
have already designed the dialog box for this example and now need only 
Process the messages in the dialog window procedure. 


on 
Calling the Dialog Box Procedure 


OwWe will call the dialog box procedure with a pointer to the current color 
ompassed as the argument: 


\ WinD1lgBox(HWND DESKTOP, /* parent window a | 
a hWnd, /* owner window mf 
ColorDialogProc, /* window procedure oe 
o NULL, /* template in resource file */ 
> COLORDIALOG, /* dialog id a 
pea &buttoncolor); /* address of current color*/ 
anand upon return from the dialog box, we will force a screen repaint in the 


new color by invalidating the entire screen: 


WinInvalidateRect(hWnd, NULL, FALSE); /* force repaint */ 


BAL. 


PDE WM_INITDLG Message 


J 


(When we first enter the dialog box, we want the radio button to be pushed 

om hat indicates the current background color of the screen. The parameter 
mp2 contains the pointer or value that we passed to the dialog on startup. In 
chis case, it will contain the color whose button we wish to highlight. 

©) Here we check the current color of the screen and send the proper radio 

embutton the message BM_SETCHECK, which not only causes this button to 

be checked, but also unchecks any other radio buttons. 


»000 04 
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static int localcolor, /* copy of color */ 
*buttoncolor; /* pointer to color*/ 


case WM INITDLG: 


buttoncolor = (int *)mp2; /*save address of color =i 
localcolor = “buttoncolor; /*copy into local variable “*/ 
switch(localcolor) /*check button for current color*/ 
begin 
case CLR RED: /* if red, save ID of red button*/ 
button = BUTN RED; 
break; 
case CLR BLUE: /“if blue save id of blue button™/ 
button = BUTN BLUE; 
break; 
case CLR GREEN: /*“if green, save green button id*/ 
button = BUTN GREEN; 
break; 
end 


/* set the button whose ID was saved to ''checked'' 
WinSendD1lgltemMsg(hWnd, button, BM SETCHECK, 
MPFROMSHORT( TRUE), MPFROMSHORT(0)); 
return((MRESULT) TRUE) ; 
break; 


©6000 0808060800080 O OC 


The parameter mp2 contains a pointer to the value of the current color.¢ \ 
We copy this to a local color variable that we change each time a button is. 
pushed. However, we don’t change the actual color unless the OK is 
selected, so we save the address of the color in another variable. Note that\_) 
these must both be static variables so that their values will remain between, 
messages passed to the dialog box. Note particularly that we must return 
TRUE from the WM_INITDLG message to tell PM that we have proc-— 
essed this message, so that it doesn’t carry out default processing and push\ 
some other button. When the program first calls the dialog box, it should | 
press the Red button, so the dialog looks like that in Figure 8-4. 


REE ET TT 
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@ Red 


o Blue 


o Green 


. Figure 8-4. The initial setting of the dialog box 





AAAI I ST 


> 


Finding Out if a New Button Has Been Pressed 


Or the user points at a radio button (or check box) and clicks the left mouse 
button, the message WM_CONTROL is sent from the radio button child 
am Window to the dialog window procedure. The lower word of the first param- 
eter mpl is set to the value BN_CLICKED and the upper word to the id of 
the button that was clicked. We can recognize this by processing the 
yWM_CONTROL messages: 


case WM CONTROL: /*control buttons clicked*/ 
if (SHORT2FROMMP(mp1)==BN CLICKED) /*if it was clicked*/ 


o~ = 
switch (SHORT1IFROMMP (mp1) ) 
begin 
case BUTN RED: 
localcolor = CLR RED; /*set local color to red “*/ 
break; 


case BUTN GREEN: 
localcolor = CLR GREEN; /*set local color to green*/ 
break; 

case BUTN BLUE: 
localcolor = CLR BLUE; /*set local color to blue */ 
break; 

end 

break; 
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Recognizing the OK and Cancel Buttons 


When the user clicks on an ordinary push button, the message 
WM_COMMAND is sent to the dialog window with the lower word of mp1 
equal to the id of the push button that sent the message. Here we need only 
recognize ID_OK and ID_CANCEL and either do or do not change the 
GlobalColor. 


case WM COMMAND: /*OK or Cancel clicked mf 
switch( SHORT 1FROMMP (mp1) ) 

begin 

case ID OK: 
*buttoncolor = localcolor; /* send out new color */ 
WinDismissDlg(hWnd, TRUE); /* if OK exit a 
return((MRESULT) TRUE) ; 
break; 

case ID CANCEL: J* 7 cancel... “y 


WinDismissDIg(hWnd, FALSE);/* leave color alone “*/ 
return((MRESULT) TRUE) ; 
break; 

end 


THE MAIN WINDOW PROCEDURE 


The command processor in the main window procedure simply has to look 
for the WM_COMMAND message, and if the command is CDIALOG, 
then start the dialog box: 


case WM COMMAND: 
swi tch(LOUSHORT (mp1) ) 


begin 
case CDIALOG: 

WinD1gBox(HWND_DESKTOP, /* start dialog box*/ 
hWnd, /*Window id xy 
ColorDialogProc, /*dialog proc ar | 
NULL, 

COLORDIALOG, /*id of dialog */ 
NULL) ; 


WinInvalidateRect(hWnd, NULL, FALSE);/*force repaint*/ 
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break; 


default: 
return(WinDefWindowProc(hWnd, message, mpl, mp2)); 


990000090 


end 
break; 


Then, when the dialog box closes, the paint routine always invalidates the 
screen, forcing a repaint to the new background color. The paint routine 
>» itself is just like ones we have seen before: 


»@ 


™) /*get size and repaint background”/ 

case WM PAINT: 
hPS = WinBeginPaint(hWnd, (HPS)NULL, (PWRECT)NULL) ; 
WinQueryWindowRect(hWnd, &rc); 
WinFillRect(hPS, &rc, buttoncolor); 
WinEndPaint(hPS); 
break; 


590090 
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In the code that follows, we illustrate the main window procedure and the 
dialog box procedure. The main program is identical to that shown in -- Fig 
-°>MAIN’ unknown --, except that the FCFNIMENU frame window creation 
) flag bit is set. 


O) 7*****Color changing program-- illustrating dialog boxes**/ 
a@, #define INCL PM 

-#include <os2.h> 

| #include <cdefs.h> 
a #include ''clrdefs.h' 


MRESULT FAR PASCAL ColorWndProc( HWND, USHORT, MPARAM, 


MPARAM ); 
MRESULT EXPENTRY ColorDialogProc( HWND, USHORT, MPARAM, 

_MPARAM cor 
radians Maion Functio , pA RKAA REAR ERRR 
—/*** has been illustrated before ee 


ee 
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MRESULT EXPENTRY ColorDialogProc(HWND hWnd, USHORT msg, 


MPARAM mp1, MPARAM mp2) \ 
begin nd 
static int localcolor, “buttoncolor; VY 
int button; Cy 
MRESULT rmsg; | 
Ww 
switch(msg) WS 
begin 
case WM INITDLG: peal 
buttoncolor = (int “)mp2; WwW 
localcolor = “buttoncolor; /*copy into local variable “/@ 
switch(localcolor) /*check button for current color*/ \/ 
begin LY 
case CLR RED: /* if red, save ID of red button*/ 
button = BUTN RED; Y 
break; WW 
case CLR BLUE: /*if blue save id of blue button*/, 
button = BUTN BLUE; Y 
break; ay 
case CLR GREEN: /*if green, save green button id *“/ @) 
button = BUTN GREEN; put 
break; WY 
end VL 
/* set the button whose ID was saved to ''checked'’ */ 
WinSendDIgltemMsg(hWnd, button, BM SETCHECK, ) 
MPFROMSHORT( TRUE), MPFROMSHORT(0O)); | 
return((MRESULT)TRUE) ; Y 
break; / 
case WM CONTROL: /*control buttons clicked*/— 
if ( SHORT2FROMMP(mp1) == BN CLICKED) /*if clicked... “Aw 
switch (SHORT1IFROMMP (mp1) ) yy 
begin 
case BUTN RED: YY 


localcolor = CLR RED; /*set local color to red “/@ 
break; 


WV 
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case BUTN GREEN: 
localcolor = CLR GREEN;/*set local color to green*/ 
break; 

case BUTN BLUE: 
localcolor = CLR BLUE; /*set local color to blue*/ 


5900000090 


break; 
end 
> break; 
Orxase WM COMMAND: /*O0K or Cancel clicked*/ 
@ switch(SHORT1FROMMP (mp1) ) 
begin 

© > case ID OK: 
a *buttoncolor = localcolor; /* send out new color */ 

WinDismissDIg(hWnd, TRUE); /* if OK exit a 
S, return((MRESULT) TRUE) ; 
oo break; 
a case ID CANCEL: fe Ti eens iii. 4 

WinDismissDlg(hWnd, FALSE); /* leave alone “*/ 
oO return((MRESULT) TRUE) ; 
am break; 

end 
ya 
a@mdefault: 
return(WinDefD1lgProc(hWnd, msg, mpl, mp2)); 
end 
(™y eturn( (MRESULT)FALSE) ; 
end 


sie ee LL aw 
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(RESULT FAR PASCAL ColorWndProc(HWND hWnd, USHORT msg, 


~ MPARAM mp1, MPARAM mp2) 
pegin 
HPS APS; /“handle to presentation space*/ 
mM RECTL res 
Static buttoncolor; 
o 
switch (msg) 
begin 


case WM CREATE: 
buttoncolor = CLR RED; /* initialize color to red*/ 
break; 


}60000 
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case WM COMMAND: 
switch(LOUSHORT (mp1) ) 

begin 

case CDIALOG: 

WinD1lgBox(HWND DESKTOP, /*start dialog box*/ 
hWnd, 
ColorDialogProc, 
NULL, 
COLORDIALOG, 
&buttoncolor); 


/* force repaint * 
WinlnvalidateRect(hWnd, NULL, FALSE); 
break; 
default: 
return(WinDefWindowProc(hWnd, msg, mpl, mp2)); 
end 
break; 
case WM PAINT: /*get size and repaint background”/ 
hPS = 


WinBeginPaint(hWnd, (HPS)NULL, (PWRECT)NULL) ; 
WinQueryWindowRect(hWnd, &rc); 
WinFillRect(hPS, &rc, buttoncolor); 
WinEndPaint(hPS) ; 
break; 


default: 
return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
break; 

end /*switch*/ 


return((MRESULT)OL); 
end 
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™) The CHGCOLOR Resource File 


~#include <os2.h> 
& #include "clrdefs.h'' 


POINTER COLORWIND chgcolor.ico 


om MENU COLORWIND PRELOAD 


vy BEGIN 
| SUBMENU ''Commands'', COLORCMD 
%, BEGIN 
~ MENUITEM ‘Dialog’, CDIALOG 
END 
©) END 
on 


-rcinclude chgcolor.dlg 


om 


© The CHGCOLOR Definitions File 
on 


m 
a NAME CHGCOLOR WINDOWAP | 


The following shows the contents of the file c Irdefs.h. 


O) DESCRIPTION ‘Color Demo Program’ 


o™ 


STUB 'OS2STUB.EXE' 
~ 


™) CODE MOVEABLE 

vam DATA MOVEABLE MULTIPLE 
YHEAPSIZE 1024 

am STACKSIZE 4096 


©) EXPORTS 
ColorWndProc @1 
ColorDialogProc @2 


5600000 


116 USING DIALOG BOXES WITH THE PRESENTATION MANAGER 


TEXT BOXES AND STRING TABLES 


©e8eeo0¢ 


A text box is a field of static text that can be displayed but not edited in a 
dialog box. Usually such fields are used as labels beside the entry fields and 
list boxes, but they are not limited to one line and can contain quite a large__, 
amount of text. Such text boxes are usually loaded from string tables. 


© @ ¢ 


String Tables 


String tables are another feature of the resource file. They allow you to keep.’ 
all text that might be application or national language dependent in a file. > 
external to the program. A string table consists of the STRINGTABLE dec- 
laration followed by any number of strings, each with symbolic or numerica 
labels: 


( 


¢ 


STRINGTABLE 
BEGIN 

CLOSEDOOR, ''Close the door!’ 
WIPEFEET, ‘Wipe your feet!"' 
END 


©0006 ¢ 


Then instead of putting the text directly in a message box, for example, you” 
load the string from the string table and display it: 


char mstring[ BUFMAX ]; 

/*get the string*/ 

WinLoadString(hAB, NULL, CLOSEDOOR, BUFMAX, mstring); 
/*display it*/ 

WinMessageBox(HWND DESKTOP, hWnd, mstring, |, MB OK); 


©86@¢ 


This effectively isolates the actual text from your program, and in another 
version of the program you could link the same EXE file with a resource filq_) 
containing 


STRINGTABLE 
BEGIN 

CLOSEDOOR, ''Fermez la porte!'' 
WIPEFEET, ''Essuyez-vous les pieds!" 
END 
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™) In both cases, the constants CLOSEDOOR and WIPEFEET are small inte- 


©» gers defined in an include file. 

on 

™), Loading Strings into a Text Box 
am 


You can also use a series of strings to load a long text message, such as a 
“ help text using a sequence of WinLoadString commands and concatenating 
) them into a long string, which will automatically be word-wrapped to be dis- 


> played on several lines. 


STRINGTABLE 
BEGIN 
Tis ''The programming of text from string tables into text boxes’ 
“ Ti+1, "is not difficult. The strings are read into the text box'' 
T1+2, ‘using the WinLoadString function, and are word-wrapped into'' 
7143, ''the text box, if the appropriate option is checked in the'' 
T1+4, ''box when it is created with the dialog editor. Then you can'' 
' T7145, ‘scroll through the text box, no matter how long it is, by'' 
T1+6, ‘receiving messages from the scroll bar and moving through'' 
: T1+7, ‘the text a line at a time.'' 


> END 


©) Then, you can load the code using a loop: 


OM) char text[1500], /*for all of help text ay 
a buf [80]; /*one line if text */ 
int id, i; 
@ id =T1; /*start with first id a | 
/*of this string table Fs 
strcpy(text, — ); /*start with null string */ 
™) for (i=0; i< TEXTMAX; i++) 
a begin 
WinLoadString(hAB, NULL, idt++, BUFMAX, buf); 
% strcat(text, buf); /*“add string to text string*/ 
m streati text, "}: /*add a space between strings*/ 
end 
o, 


a@ /*load into the text box”/ 
WinSetD1lgltemText (hWnd, TEXTBOX, text); 


ALL 
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SCROLL BARS 


&©8600600@ 


Scroll bars appear automatically on list boxes such as we will be using to 
select filenames, and can also be made part of any standard window if you\W/ 
want to scroll a large image through a smaller viewing area. J 

You can also include a scroll bar directly in a dialog box alongside a text 
box and use it to scroll through a large amount of text. If you include a ver- 
tical scroll bar, clicking the mouse on it will generate a WM_VSCROLL\W 
message, and a horizontal scroll bar will cause a WM_HSCROLL message.(__ 

When the scroll messages are received in a dialog box, the upper part of 
mp2 contains one of the following messages: 


WY 
SB_LINEUP The mouse has clicked on the upper arrow. © 
SB_LINEDOWN The mouse has clicked on the lower arrow. ? 
SB_PAGEUP The mouse has clicked on the area abovet_) 
the slider, or the PgUp key has been 
pressed. w~ 
Y 
SB_PAGEDOWN The mouse has clicked on the area below 
the slider, or the PgDn key has been 
pressed. V/ 
SB_SLIDERPOSITION Sent to indicate the final position of the 


slider. The lower part of mp2 contains a\__ 
normalized value between 0 and 100 repres-¢ \ 
enting the percent of full scale (bottom = 


100, top =0). yy 
SB_SLIDERTRACK Sent every time the slider position changes. aed 
WY 

SB_ENDSCROLL Sent when the user has finished scrolling. _ 
od 


Each of these messages occurs when the slider has been moved by the user. 
The slider is not actually redrawn in this position, however, unless your 
program accepts this new position. Then it must send the slider a message 
indicating the new position: | 
hocrol |. = 


WinWindowFromID(hWnd, VSCROLL); /*get the scroll bar id*/ 
WinSendMsg(hScroll, SBM SETPOS, (MPARAM)posn, NULL); 


©6008 00<¢ 
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The SLIDEBOX Program 


The SLIDEBOX program illustrates how to bring up a dialog box consisting 
of a vertical scroll bar, a text box and an OK push button as shown in 
™)Figure 8-5. The main program and the main window procedure of the 
amSLIDEBOX program are identical to those shown earlier except for the 
command to start the dialog box: 


a case WM COMMAND: /“interpret commands */ 
switch(LOUSHORT (mp1) ) 

oO begin 

oN case SHOWDLG : /*change text to Foogie”/ 

WinD1gBox(HWND DESKTOP, hWnd, BoxDlg, NULL, LDLG, 

“ NULL); 

los break; 

“ default: /*“else do nothing a 

a return(WinDefWindowProc(hWnd, msg, mpl, mp2)); 

o> end 


am The dialog procedure is shown below: 


mvoid LoadWin(HAB hAB, HWND hWnd, int scroll, int max) 
begin 
| int 13 
char text[BUFMAX], buf[BUFMAX ]; 
strepy(text, °"'); 
while (scroll < max) 


) 


) 


‘ates | begin 
om WinLoadString(hAB, NULL, scroll++, BUFMAX, buf); 
ee | 
strcat( text, ); 
ey strcat(text, buf); 
Fame’ end 
WinSetDlgltemText(hWnd, TEXTBOX, text); 
end 
ff. t ... b.b bw .wk w.b b w b b b  b b b b b b b b .b b b b b ob b.b b .b.b .b.bb .b.b bb ob. 
Bf ELE IN ESOS CERT E ESS UES TUN TEARES GET ES ETRE S ECOG Moe eN POPE Os ARE EN ore edpamaaaet § 


veMRESULT EXPENTRY BoxDIg(HWND hWnd, USHORT msg, 
| MPARAM mp1, MPARAM mp2) 
begin 
int i, itemid, posn; 
Static scroll, max; 


}0ed090 
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The programming of text from 
string tables into text boxes is 
not difficult. The strings are 
read into the text box using the 
WinLoadString function, and 
are word-wrapped into the text 
box, if the appropriate option 
is checked in the text box 





Figure 8-5. The SLIDEBOX program display 


Static HWND hScroll; 
BOOL draw; 


switch (msg) 


begin 
case WM INITDLG: 
hScroll = 
WinWindowFromID(hWnd, VSCROLL); /“get scroll bar id */ 
scroll] = TT; /*initialize text box*/ 
max = Tl + TEXTMAX; /*maximum line to. load*/ 


LoadWin(hAB, hWnd, scroll, max);/*“load text into box*/ 


/*be sure dialog is active”*/ 
WinPostMsg(hWnd, WM BUTTONIDOWN, OL, OL); 
return (TRUE); 

break; 


case WM VSCROLL: 
draw = TRUE; /*indicates box should be redrawn*/ 


switch(SHORT2FROMMP (mp2) ) 
begin 
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case SB LINEDOWN: /*go down one line 
if (++scroll > max ) then scroll = max - 1; 


break; 


case SB LINEUP: /*go up one line oF 
if {--seroll < T1) then scroll = Tt 
break; 


case SB PAGEDOWN: /*page down mi 
scrol|] += 54; 
break; 


case SB PAGEUP: /*“page up a 
scroll == 5; 
if (scroll < Tl) then scroll = 11; 
break; 


case SB SLIDERPOSITION: /* move to new =f 
/* slider position */ 
scroll = 
((LOUSHORT(mp2) * (long)TEXTMAX)/100L) + T1; 
break; 


default: 

draw = FALSE; /*do not redraw on other msgs*/ 
end 
if (draw) then 

/*redraw text box 

LoadWin(hAB, hWnd, scroll, max); 
/*set slider positon*/ 
posn = (scroll - T1)* 100 / TEXTMAX; 
WinSendMsg(hScroll, SBM SETPOS, (MPARAM)posn, NULL); 
break; 


case WM COMMAND: 
switch(SHORT1FROMMP (mp1) ) 


begin 

case DID OK: 
WinDismissD]lg(hWnd, TRUE); 
return( TRUE) ; 
break; 
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end 
break; 


default: 
return(WinDefD1lgProc(hWnd, msg, mpl, mp2)); 
end 
return((MRESULT)FALSE) ; 
end 


THE MULTILINE EDIT BOX 


One of the most useful functions in OS/2 1.2 is the addition of the multiline 
edit (MLE) box. This is actually a fairly full-featured text edito that can be 
used to operate on text buffers up to 65535 bytes long. To use an MLE box, 
simply create a dialog box with the dialog box editor that has a MLE edit 
box and, at the minimum, an OK and Cancel button. 

Then, in processing your dialog, you need to load text into the MLE box 
at WM_INITDLG time and read it back out when OK is pressed. You do 
this by establishing a buffer and sending messages to the MLE box to 
import or export text. 

Text is sent to the MLE box as a single buffer of up to 65536 bytes in 
length, with newline characters separating lines. There are actually three 
text formats allowed, one from programs written for Microsoft Windows, 
and two others. The most common are MLEFIE_CFTEXT and 
MLFIE_NOTRANS. The NOTRANS format guarantees that the text will 
be re-exported in exactly the same form it was imported, while the 
MIFIE_CFTEXT format translates CR, CR-LF and LF-CR as line break 
characters on import. To import text to the MLE box you do the following: 


/ aE OTT PTE EN NT eee PORTE LT PER IT EMOTE er OOe Se tert a SPE Fa ee CER Sl TRE ei Al eR ee al } 
/* Initialize the MLE edit box and load it / 
/ | EIT pT NTT a EET TORN cE ae ARN AER On Pee eee Pn OE Te eC TNE Oe oe ONCE Tee jf 


ULONG i, posn, result, bytes, rc; 


case WM INITDLG: 


buf = malloc(MAXBUFLEN) ; /*allocate text buffer*/ 
strcpy(buf, 
Initial text on display); /*out text in it a 


©0008 HOOOOOOOOOCOHOHOOOOOOOOO8OGO< 


996O GOO OOHHHHHHHHOOHOHOOHSOHHOSOOSOSOSD 


THE MULTILINE EDIT BOX 123 


WinSendD1gltemMsg(hWnd, MLEBOX, 


MLM_SETIMPORTEXPORT , /*set address of buffr*/ 

(MPARAM) buf , 

(MPARAM)MAXBUFLEN) ; oaths Bios ey 
WinSendD1g!temMsg(hWnd, MLEBOX, 

MLM FORMAT, /*set the format =) 

(MPARAM)MLFIE CFTEXT, 

NULL); 
result = strlen(buf); /*get the text size “*/ 
posn = 0; /*position to start “*/ 
WinSendD1lg!temMsg(hWnd, 

MLEBOX, /*import the text ay 

MLM_ IMPORT, 

(MPARAM)&posn, /*starting here i 

(MPARAM)result); /*this size * 
return ((MRESULT) TRUE) ; /*and exit x / 
break; 


Getting the edited text back from the MLE box just amounts to exporting 
the text back to the buffer and storing it: the format and buffer address do 
not have be set again. The first parameter to the MLM_EXPORT message 
is the position in the buffer where the text is to be inserted. After the export 
is completed, this parameter contains the number of bytes exported. 


 diatatetatatatatetetatatatetatatatateanetatannanamateatenatatateiaataataaatataiataaiaataataaemaata a 
/* Export the text back from the MLE box and store it Ay 
 icaeiatatataiataaiataaataaataaaeataanaaaeatamaeaaiaantaatetaaaataaaataaataae yf 
case WM COMMAND: /*O0K or Cancel clicked “*/ 
switch(SHORT1FROMMP (mp1) ) 
begin 
case DID OK: 
posn = 0; /*insert position 5 


bytes = MAXBUFLEN; 
WinSendD1lg!I temMsg(hWnd, 


MLEBOX, 

MLM EXPORT, /*export the text | 

(MPARAM)&posn, /*“becomes # exported ny 

&Ebytes); /*number length changes “*/ 
/*store the text ina file a 
f = fopen(''words.txt'',''w''); /*“open the file iY 


for (i=0; i <= posn; i++) 
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fputc(buf[i], f); /*“put chars in file x 

fclose(f); /*then close the file * ff 

case DID CANCEL: /*start here if cancel sj 
free(buf); 


WinDismissD1lg(hWnd, TRUE); 
return((MRESULT) TRUE) ; 
break; 
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The trickiest things about the MLE box are the use of the two parameters to 
the messages. Both are pointers to longs and both get changed during the ‘? 
calls. Be sure that you use longs for these variables and be sure that you 
reset the value of the position before calling EXPORT. The text will not 
necessarily end with a null byte after you have edited, so you must be careful \/ 
to use the position count value. Finally, you should note that the buffer may (_) 
be longer when you export it than it was when you started and allow space = 
for it. 


\ 


WW 
J 
USING HELP HOOKS TO DISPLAY HELP MESSAGES 
A hook is a routine that intercepts messages before they are sent to specific _ 
windows. You can set a hook to intercept specific classes of messages and | 


send them to special window procedures. To do this, you use the command 
WinSetHook, which has the calling sequence 


WinSetHook(hAB, hmq, hooktype, hookproc, modid); 
hooktype one of the following hook types: 


HK_HELP any occurrence of WM_HELP, 
MIS_HELP, BS_HELP, or MB_HELP. 
HK_INPUT called when messages are removed from “ 


0806 @¢ 


the message queue before being returned by \_) 
WinGetMsg or WinPeekMsg. &) 

HK_JOURNALPLAYBACK whenever a message is to 
be played back. 

HK_JOURNALRECORD after input it translates into WY 
WM_CHAR or, 
WM_BUTTONI_DBLCLCK for 
recording messages into a journal. 
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hookproc 


modid 
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HK_SENDMSG called whenever WinSendMSg is 
called. 


The address of a procedure to be called by the hook. 


The id of a resource if loaded, or NULL if being 
installed in the system message queue. 


When a message is intercepted by one of these hooks, the hook procedure 
is called with the following parameters: 


helphook(hAB, mode, topic, subtopic, &rect); 


where 


mode 


topic 


subtopic 


& rect 


is HFM_MENU, HFM_MD, HFM_WINDOW, or 
HFM_APPLICATION, indicating the mode in which 
help has been requested. 


In menu mode this is the menu id: in message box mode 
this isthe message id; and in standard mode this is a 
window id. 


In menu mode, this is a command id; in message box 
mode this is a control id; and in standard mode this is the 
id of the window with the focus or -1 if none. 


The address of a RECTL structure containing the screen 
area from which the help was requested. 


As you can see, if you carefully give each window and message box a 
known id, you can tell the context from which help was detected and decide 
which help message to display. You can request help at any time by pressing 
Fl, which has the default WM_HELP accelerator associated with it, by 
selecting Help from the menu or by selecting a HELP push button in a 
message or dialog box. 


1. If you request help by pressing Fl while a top-line menu item is 
selected, the topic will be the id of this menu item and the subtopic will 


be -1. 


2. If you request help from a drop-down menu item, the topic will be the 
top-line menu item and the subtopic the id of the selected item. 





ii 
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3. If you request help from the main window, the subtopic will be the main 
window id. 


eee 


4. If you select a help button from a message box, the topic will be the, 
window id specified in the WinMessageBox call. 


5. If you select a help button from a dialog box, the subtopic will be the 
dialog id used to reference the dialog template in the resource file. 


© @< 
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( 


From the id passed to the hook, you can select the correct text strings from | 
the string table and load and display them. 
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a Using the Help System in 
OS/2 PM 


9600000900808 OO 


ry OS/2 1.2 has a sophisticated help system that allows you to write and 

™) format help screens using a simple scripting language and include index 
entries and links to additional screens so that each help screen can take on 
the features of a hypertext system. 

© ~The help screens can be written using any text editor and formatted by 

™) including markup commands that are identical to those used in IBM’s 

m Bookmaster text processing system. Thus, you can write a manual for your 
program using Bookmaster and include the same text in the same form in 
the help screens. 


o 


e MARKING UP HELP SCREEN TEXT 
om, 


om A markup language is a series of symbols that tell some text formatting 
program how to space, format, and index the text that makes up a help 
screen (or manual). In OS/2 the program that compiles the help files is 
©) called IPFC for the Interactive Presentation Facility Compiler. Nearly all of 
™, the commands in a help file begin with a colon and end with a period. Many 


oo, 
@ sol. begin an ordered list 


occur in pairs such as 


seol. end the ordered list 
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where the second of the two is the same command as the first but preceded 
with the letter “‘e.”’ 


The tags that we use to mark up the text divide into groups as follows: 


e headers 

e linking commands 

e lists and definitions 

e formatting commands 
e index entries 


Formatting Commands 


Formatting commands are used to affect the layout of text on the page, as 
well as the structure of the document: 


suserdoc. -:euserdoc. Must start and end any IPF source file. 

:p. Starts a new paragraph. 

shp1. - :ehp1. Sets the text between the markers in /talics. 

=hp2.-:ehp2. Sets the text between the markers in bold- 
face. 

Headers 


Headers are used to label groups of paragraphs and start individual help 
panels. They range from #1 to #6 heads and are specified as follows: 


sh1. chapter head— used to start a panel 
:h2. principal subhead— starts panels 

:h3. secondary subhead— also starts panels 
:h4.-:h6. minor subheads— do not start panels 


The IPFC program requires that you start with :hl. heads and use them in 
sequence down to the lowest level you plan to use, without leaving any inter- 
mediate heads out. 
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Lists 


MARKING UP HELP SCREEN TEXT Zo 


There are four types of lists allowed by IPFC: 


simple lists 
ordered lists 
unordered lists marked with bullets 


definition lists 


The above list of names of lists is a simple list, where each element starts on 
a new line. An ordered list is simply a numbered series of items, and an 
unordered list is a list of items preceded by bullets: 


e unordered list 


e each item is marked 


° using a bullet 


The markup symbols for these lists are 


ssi. 


:esi. 


:ol. 


:eol. 


:ul. 


:eul. 


begin simple list 

end simple list 

begin ordered list 

end ordered list 

begin unordered list 

end unordered list 

begin a new list item of any of these types 


Thus, the markup code for an unordered list like that shown above would be 


“ul. 


:li.unordered list 
:li.each item is marked 
:li.using a bullet 


seul. 


Each of the epeesed ae lists can also be modified with the compact modifier 
to print with less space between lines. 
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WY 
Definition Lists Ww 


A definition list is one in which a boldfaced column of items appears at the 
left, with an indented series of definitions adjacent to them. A definition list 
for the list types appears just above. There are four markup symbols used in) 
specifying definition lists: 


:dl tsize=nn. start a definition list with a left column width of na. ® 
:dt. Start a definition tag to appear in the left-hand column. (_) 
:dd. Start a definition to appear in the right-hand column. \vV 
:edl. end a definition list. | WY 


As with the other lists, these can be compressed by including the compact 
modifier as part of the dl marker. A typical definition list might look like the 
following: 


lists used to enumerate data 
hp tags used to highlight phrases 
headers used to start sections of a document 


The above definition list is typed in as 


:d]l tsize=10 compact. 

:dt.lists 

:dd.used to enumerate data 

:dt.hp tags 

:dd.used to highlight phrases 
:dt.headers 

:dd.used to start sections of a document 
:edl. 
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LINKING PANELS TOGETHER 


The most powerful part of the help system in OS/2 is the ability to click the 
mouse on a highlighted word and have a new panel appear describing that_) 
feature in more detail. To highlight a word or phrase that you wish to have ) 
linked to another panel, you use the :link. marker around the phrase 


YO 
VY 


Lg 
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ar, 


om: link reftype=hd res=2000. 
reading files 
:elink. 


This says to link the phrase “‘reading files” to a header of a panel whose id is 
©) 2000. Then, that panel should begin with a header that contains that id 
©) number: 
©) :h2 res=2000.Reading in Files 
on 


) could be related to window identifiers within your OS/2 program. However, 


You should realize that the symbolic values that you define for these panels 


~@ while it is common to refer to each window by a symbolic identifier, IPFC 
requires that these integer values be referred to only as numbers. It is up to 
you to make this association either with comments or with values in the Help 

table, which becomes part of your resource file. 

a, One method of using the symbolic constants defined in an include file to 
| represent these integers is to use the C preprocessor, which will read in the 
include files and substitute the values for the named constants. This 


66 599 
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©) produces an output file with an extension which you can then process 


©) with IPFC. To use the preprocessor simply type 
fr cl /c /P ipfile.ipf 


) This will produce the output file names “ipfile.i.””> You will need to edit this 
a) file to remove about 50 lines of blank lines which are inserted by the C pre- 
processor. Certain other C symbols are also converted, most typically “‘.e”’ is 
converted to “.E0,” and must be restored before running IPFC. Other third 
party vendors will probably also produce tools which will take care of this 


™)step. 
om 
©) Constants Used by HELPJ 
We will use the following constants in the HELPJ program below. We 


define them here so you can see the relationship between the named con- 
stants and the integer values we will use to define help panels in the IPF file. 


}@@eed@ 
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#define 


#define 
#define 
#define 
#define 
#define 


#define 
#define 
#define 


#define 
#define 
#define 


#define 
#define 


PROGWIND 


MAIN HELPTABLE 


SUBHELP 
EXTENDED HELP 
HELP FOR HELP 
KEYS HELP 


F | LEMENU 
OPEN 
EAT 


DISPLAY 
LINETYPE 
SETCOLOR 


EDIT 
MOVESIZE 


2000 
2010 
2020 
2030 
2040 


100 
110 
120 


200 
210 
220 


300 
310 


This file defines the window id, the help table ids and the menu values. 


THE HELP RESOURCE FILE 


When you create a help file, you must include information on the help mes- 
sages to be processed in your program’s resource file. These include a main 
line help menu on the menu bar, a main help table, and a help subtable. 


fw I Ie Ie I te 
NON AN IN IN IN IN IN IRIN INN 


/*** Resource file for the HELPJ program™***” / 
#include ‘‘helpj.h' 

#include <os2.h> 

POINTER PROGWIND helpj.ico 


MENU PROGWIND PRELOAD 


BEGIN 
FiSBBMENU. ''  =FILEMENU 
BEGIN 
MENUITEM ''SeqvOpen...'', OPEN 
MENUITEM ‘Exit’, EXIT 
END 
SUBMENU ''SeqvDisplay, DISPLAY 
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BEGIN 
MENUITEM ‘'LineType’, LINETYPE 
MENUITEM ''Color'', SETCOLOR 
END 

SUBMENU ''SeqvEdit', EDIT 
BEGIN 
MENUITEM ''Move/Size', MOVESIZE 
END 

SUBMENU ''Help'', WM HELP 

begin 


MENUITEM ''&eqvHelp for help...'', HELP FOR HELP 

MENUITEM ‘'SeqvExtended help...'', SC HELPEXTENDED, 
MIS SYSCOMMAND 

MENUITEM ‘'SeqvKeys help...’ , SC_HELPKEYS ; 
MIS SYSCOMMAND 

MENUITEM ‘'Help Seqvindex...'', SC _HELPINDEX , 
MIS SYSCOMMAND 


ASTI IEITTTIIT TIT 


end 
END 
oO 
HELPTABLE MAIN HELPTABLE 
O) BEGIN 
m HELPITEM PROGWIND, SUBHELP, EXTENDED HELP 
END 
o 
eo) HELPSUBTABLE SUBHELP 
BEGIN 
, HELPSUBITEM EDI Ts EDIT 
om, HELPSUBITEM FILEMENU, FILEMENU 
> HELPSUBITEM DISPLAY, DISPLAY 
| HELPSUBITEM LINETYPE, LINETYPE 
OY END 


©) For each panel that you want displayed, you must have an entry in the 
™) HELPSUBTABLE. This associates the window id’s with the panel id’s. 


6600060 
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Interpreting the Help Messages 


The main line Help menu by convention includes the commands “Help for 
Help,” “Extended Help,” and a “Help Index.’’ You may also include the 
menu item “Keys Help” and copy that help text from the sample provided in 
the OS/2 1.2 Toolkit. The “Help for Help” menu item posts a 
WM_COMMAND message with mp1 set to the message in the menu, 
which you then intercept in your main window procedure and post the 
message HM_DISPLAY_HELP. 


case WM COMMAND: 
switch (SHORTIFROMMP(mp1)) ; /*Get the command value*/ 

begin 

case HELP FOR HELP: 
WinSendMsg( hHelpInst, HM DISPLAY HELP, OL, OL); 
break; 

end 

break; 
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The three remaining help menu selections post system commands that \_) 
result in actions by OS/2 PM directly. Selecting “Extended Help” causes 
the system to post a WM_HELP message that is intercepted by the help 
instance processor, causing a display of the main help panel for your Y 
program. i, 
The ‘Keys Help” selection posts the message ( \ 
HM_QUERY_KEYS_HELP, which you respond to by posting the > 
number of the window panel where your keys help message begins. This is Yo 
the text you copied from the toolkit HEIP example. You can also easily omit Wy 
this panel unless you have additional special keys you wish to explain, since wy 
it is available under the main PM “Help for Help” window. The messages 
to cause the keys help to appear are 


WY 

case HM QUERY KEYS HELP: i 

return( (MRESULT) KEYS HELP); YW 

break; ‘? 

The “Help Index” menu item posts the message SC_HELPINDEX, \_ 
which causes a display of all the items indexed in your help IPF file. You 


can click on these index items and go directly to that point in the help 


{ 


C 


panels. 
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INDEXING ITEMS 


The Help manager and the IPFC compiler also provide the ability to gen- 
erate an alphabetical index of topics. These are automatically linked to their 
appearance in the text and clicking on the “Options” menu of the help 
window will allow you to select an index. 

There are two levels of indexing provided: :il. and :i2.. To make a main 
line index entry, simply include the word preceded by the :il tag: 


:11.File menu 


To include subindex entries, you simply give the main entry a symbolic 
name that you then refer to in all subindex entries: 


AALAIT IAI TT 


2:11 ta=filemen.File menu 
:12 refid=filemen.opening files 


oo 
©) THE COMPLETE HELP IPF FILE 

o 

> Below we show a simple help file with some linked panels. Note that the 
main panel is given the res value 2020, which is equal to the 
~ / EXTENDED_HELP value in the symbol definitions. This equality is 
©) required if you want a main help panel to appear when you press F1 or select 
amy the “Extended Help” menu item. 


@my :userdoc. 
:title.Help for Display/2 
>, : p play 
>body. 


OY) :hl res=2020.Help for Main Screen 
:p. To use this package, simply click on any pull-down 
menu and select from the menu which appears. While a menu 
OY is pulled down, you can press Fl for help on that topic. 
m :dl tsize=15. 
:dt.: link reftype=hd res=100.File:elink. 
©) :dd.read in ASCII data files. 
am :dt.: link reftype=hd res=200.Display:elink. 
arene the data display 
:dt.: link reftype=hd res=300. 
a» Edit 


:elink. 
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:dd.move, size, and erase data. 

sed! 

shi res=100.File Menu 

>11.File menu 

The File menu allows you to read in data files 

>h1l res=200.Display Menu 

:11.Display menu 

The display menu allows you to change the color and line 
type. 

dil tsize=10. 

:dt.: link reftype=hd res=210. 

Linetype 

:elink. 

:dd.Allows you to change the line type 

:dt.Color 

:dd.Allows you to change the line color 

:edl. 

:h2 res=Z210.Line Type 

:p.This command brings up a dialog box allowing 

you to select the line type using a series of radio 
buttons. 

=hl res=300.Editing the Display 

:p.The Edit Menu allows you to move lines around on 
the screen. 

: index. 

:euserdoc. 


Compiling a Help File 
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Once you have created your help text file using a text editor, you simply 
compile the file using the IPFC compiler. It is conventional to give the help 
source file the extension .[PF and the compiled file the extension .HLP. Thu 


following command produces the file HELPJ.HLP: 


PPro AELPd« [Pr 


o< 


The help file must be accessible when you start the program that requires it 
You can put it either in the same subdirectory as the program you ar_) 


running or in a subdirectory specified by the environment variable HELP. 


Sec 
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REGISTERING A HELP INSTANCE 


A program will invoke these help features if a help initialization structure is 
filled with the correct values and a help instance is created and associated 
oywith the main window frame. To load the help initialization structure hmi, 
em You fill it as follows: 


HELP INIT hmi; /*declare help structure*/ 
HWND hHelpInst; /“help instance window “*/ 

abhmi.cb = sizeof(HELPINIT); /*size of help structure*/ 
hmi.ulReturnCode = NULL; 

o 


hmi.pszTutorialName =NULL; 
M)hmi.phtHelpTable = /*value of help table “*/ 
(PVOID)(Oxffff0000 BitOR MAIN HELPTABLE) ; 

hmi.hmodAccelActionBarModule = NULL; 

Ohmi. idAccelTable = NULL; 

a@pyhmi.idActionBar = NULL; 
hmi.pszHelpWindowTitle=''Example Help Window’; /*title bar*/ 

nmi .hmodHe IpTableModule = NULL; 

emhmi .usShowPanelld = NULL; 


sini -pszHeIpLibraryName=""HELPJ.HLP'; /*name of help file */ 


Then you must create the help instance and associate it with the current 
frame window: 


/*create the help instance*/ 
yhHelpInst = WinCreateHelp|Instance(hAB, &hmi); 


/*associate with a window*/ 
(WinAssociateHelp|Instance(hHelpInst, hFrame); 


Once these functions are executed, then either pressing function key F1 or 

selecting Extended help will automatically bring up the main help window. 

a The display of the help window using the text above is illustrated in 
Figure 9-1. 

o 
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eee 
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[Help Example 
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Help for Main Screen vis] 
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To use this package, simply click on any 
pull-down menu and select from the menu 
which appears. While a menu Is pulled 
down, you can press Fl for help on that 
topic. 


C 


C 


read in ASCIl data files. 
Display Change the data display 


Edit move, size, and erase data. 
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Figure 9-1. A Help example window 
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10 Using the Graphics Pres- 
entation Interface 


ZIT TT ITT 


Mos /2 PM has an extensive set of calls for drawing graphical images on the 
emscreen, all having the prefix Gpi. These calls allow you to draw lines, curves, 
boxes, markers and fonts, fill areas, and move bitmaps on the screen. You 
nave the ability to set the line type, color, and fill pattern and draw a 


umber of different point markers in a few simple calls. 
oy 


“PRESENTATION SPACES 

ma 

all Gpi calls have the handle to a presentation space as an argument. 
Recall that there are three types of presentation spaces 


e cached micro 
-@ micro, and 
' )e normal 


The cached micro presentation space is an existing internal table that is 
nitialized and passed to you when you make a WinBeginPaint call. It has no 
emmemory from previous invocations and you must set the color, line type, 
gegen type, and font each time you use it. 

-_ The micro presentation space is created with the GpiCreatePS call with 
he option GPIT_MICRO bit set. A micro presentation space is useful when 
you need to create and reuse a PS with a number of settings that differ from 
athe defaults. 
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eee 


The normal presentation space is created with the GpiCreatePS call with 
the option GPIT_NORMAL bit set. A normal presentation space not only 
allows you to save various settings and colors, but also allows you to record 
all of your graphics drawing commands in a graphics segment that can be\_» 
played back rapidly each time you want to repaint the screen. In addition, a, 
normal segment can be used for drawing both on the screen and on other 
devices simply by associating a new device context with the presentation — 


space and redrawing the segment on the new device. a, 
WY 


GRAPHICS COMMANDS UY 


Many of the Gpi drawing commands operate on a POINTL structure that. 


gives the current x and y location where the operation 1s to take place. Note 
that you must pass the address of the point structure. Ww 
POINTL pt; /* point structure a Vv 
pt.x = 50; /* set x-coordinate a 
pt.y = 100; /* set y-coordinate oe baad 
WwW 
GpiMove(hPS, &pt); /* move to that point wr ©) 
pt.x = 200; /* set a new x-value or 
GpiLine(hPS, &pt); /* draw a line to that point “*/ VY 
Graphics Coordinate Space Y 
WY 


Usually, you make calls to graphics functions using units of pixels or pels. 
These two terms are used in different engineering disciplines but have iden- 
tical meaning. The coordinate system of a PM screen has (0,0) in the lower 
left corner and a maximum (x,y) value in the upper right corner. You can\_) 
always find out the current size of your window. with the, | 
WinQueryWindowRect call, which returns the coordinates of the window in 
a RECTL structure. | 
It is also possible to tell PM that a window is to use a different coordi_) 
nate system, such as 0.1 millimeters or 0.01 inches, by setting suitable option 
bits in the GpiCreatePS call, but these bits are only interpreted accurately 


C 
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when the graphics are drawn to a plotter or printer. The representation on a 
epscreen is not exact. 


ao 


athe GpiCreatePS Call 


This call has the form 


on 
GpiCreatePS(hAB, hDC, &size, options); 


where 
hAB 


a hDC 


) 


»o@ 


size 


options 


AAAI ETT 


is the handle to the anchor block. 


is the handle of a device context with which the presentation 
space is to be associated. This value must be non-null if the 
GPIA_ASSOC bit is set in the options, or if a micropresenta- 
tion space is specified. 


is the address of a SIZEL structure, containing the long value 
of the x size in 


$1Z.€xX 

and the y size in 

S1Z.Cy. 

is a series of bits defining the units, format, and type of PS. 
units describes the screen units 


PU_ARBITRARY any convenient units 
PU_PELS units are pels or pixels 
PU_LOMETRIC units of 0.1 mm 
PU_HIMETRIC units of 0.01 mm 
PU_LOENGLISH units of 0.01 inch 
PU_HIENGLISH units of 0.001 inch 
PU_TWIPS units of 1/1440 inch 


format indicates whether the segments will be retained in long 
or short format. Can be set to GPIF_LONG or 
GPIF_SHORT or GPIF_DEFAULT, which is the 
same. 
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type type of presentation space. Select GPIT_NORMAL or 
GPIT_MICRO. 


| 
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association can be set to .GPIA_ASSOC -— or 
GPIA_NOASSOC. If associate is set then hDC must 
be a valid handle to a device context, obtained with 
DevOpenDC. : 


DRAWING A SPECTRUM 


A spectrum is a series of data points acquired at evenly spaced time inter- 


060 @ ¢ 


vals. They are best displayed by drawing a series of continuous lines between 
adjacent points. If there are a large number of data points, you may have to Wy 
scale the data to fit into your window. In this case, the space between data (_) 
points will be calculated as a fractional number of pixels so that the entire 
spectrum will fit into the window. As a simple algorithm, the Paint proce- 
dure consists of 


1. Get the current window width. 
2. Divide the width by the number of points. The result is the x increment. 


3. Move the drawing point to the leftmost position. 


@@eeeé 


4. Draw a line to each successive y-point, incrementing the x-pixel position , 


by the amount calculated. yn 
uy 
This can be represented as follows: LY 
xinc = (long) (65536L*(float)rc.xRight /(float)XDIM); & 
err=GpiSetColor(hPS, CLR WHITE); 
xpos = OL; /*set initial x posn a 
Aik = 0; YY 
pt.y = x[0]; /*set initial y posn a | 
err=GpiMove(hPS, &pt); /*move to first point xp 
xpos += xinc; /*increment 32-bit to next x*/ (|) 
for (i = 1g f= RDIMe TF) 6) 
begin bond 
pt.x = (int)(xpos >> 16); /*get next x pos from top 16*/ \J 
pt.y = x[i]; /*get next y */ &) 
GpiLine(hPS, &pt); /*draw line a 
‘= 
LU 
, 
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AAAL, 


xpos += xinc; /*fractional increment f 

end 

on, st ; , 
/WinQueryUpdateRect(hWnd, &rc); /*“repaint window 

©) WinValidateRect(hWnd, &rc, TRUE); 


The disadvantage of this technique is obvious for large numbers of data 
@ypoints: it is very slow and can take one or more seconds to draw the spec- 
trum on the screen. 


on”, 


ao 
_~ Packing the Spectrum into a Buffer 


YA more efficient technique for drawing spectra consists of making up a 
@™) buffer consisting of an array of the maximum and minimum data points in 
the group of points that would fall on top of each other when plotted on a 
screen of limited resolution. For example, if the screen width were 640 
© pixels, then a 4096-point spectrum would consist of 4096/640 or 6.3 data 
points superimposed on each pixel. Rather than drawing a series of lines 
between 6 points, we determine the maximum and minimum of the group of 
‘points that would be plotted on top of each other and simply draw a vertical 


line between these maxima for each pixel column: 


Dis par bit = (float)XDIM/(float)rc.xRight; 


Mj = 0; 

leftpnt = 0.0; 
~ /*#i11 the buffer with mins and maxes*/ 
Orightpnt = pts per bin; /*size of one bin “*/ 
a@while(rightpnt < XDIM) 

begin 

@ nin= 10000; /*find max and min “*/ 
Mm, max = -10000; /*in each group * 
a for (i = (int)leftpnt; i < (int)rightpnt; i++) 

begin 
om if (max < x[i]) then 
- max = x[i]; /*set new maximum a 

| if (min > x[i]) then 
a) min = x[i]; /*set new minimum = 
am end 

buffer[ j++] = min; /*put min and max a 

fy buffer[ j++] = max; /*in buffer uF 
m leftpnt += pts per bin; /*go on to next group*/ 
“ 
wm, 
“a 
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rightpnt += pts per bin; /*“of points a 
end 
bufmax = j-1; /*remember how big the buff&_) 


WinlnvalidateRect(hWnd, NULL, TRUE); & 


Then, to draw the spectrum, you only need to draw vertical lines at each > 


x-pixel position: 


i, 

j= 9; 
pix =O YY 
while (j < bufmax) /*draw lines from display buffer*/ WW 
begin 2 
pt.¥ = buffer] jr]; ae 
GpiMove(hPS, &pt); /*move to bottom of each bin x1 
pt.y = BUTTEer| per]; & 
GpiLine(hPS, &pt); /*“and draw line to top of bin “*/ | 
pEexrr; WS 
end ‘oS 


Now, the only problem with this algorithm lies in the case of a lively or noisys 


spectrum in which the maximum value in one pixel column is less than the 


minimum in the adjacent column. In this case the spectrum would appear to, 


C 


have discontinuities. This is easily solved by checking the previous column’s 


maximum and minimum before drawing the new column: 
if (min > oldmax) then 

min = oldmax; /* lower new min a 
if (max < oldmin) then 

max = oldmin; /*raise new max a 
oldmax = max; /*save for next column*/ 


Ooldmin = min; 


Line Types 


©0080 


- 


The default line type is solid and one pixel wide. You can change the line 
type to several other types using the call 


GpiSetLineType(hPS, type); 


where type can be one of the following: 
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LINETYPE DEFAULT LINETYPE LONGDASH 
LINETYPE DOT LINETYPE DASHDOUBLEDOT 
LINETYPE SHORTDASH LINETYPE SOLID 
LINETYPE DASHDOT LINETYPE ALTERNATE 
LINETYPE DOUBLEDOT LINETYPE INVISIBLE 


Ziti gg. 


Point Markers 


) 


OWou can mark data points with markers provided as part of the character 

eomset. These markers include a cross, plus, diamond, square, six-pointed star, 
eight-pointed star, solid diamond, solid square, dot, small circle, and blank. 
You select the type of marker with the call 


GpiSetMarker(hPS, type); 


a’ 
where type is one of the following constants: 
om MARKSYM CROSS MARKSYM_ SOL1IDD1AMOND 
Ps MARKSYM PLUS MARKSYM_ SOL I DSQUARE 
. MARKSYM_ DIAMOND MARKSYM DOT 
em MARKSYM SQUARE MARKSYM SMALLCIRCLE 
am MARKSYM S|IXPOINTSTAR MARKSYM_ BLANK 

| MARKSYM_ EIGHTPOINTSTAR 
oO 
_— to draw the markers you use the call 


GpiMarker(hPS, &point); 


J 


where point is a POINTL structure, just as is used in the GpiLine call. 


lie 
@Polylines and Polymarkers 


On you have a series of lines to draw, as in a spectrum, and all are repres- 
(vented as a series of (x, y) data pairs as pixel coordinates, you can create an 
marray of POINTL structures defining these drawings and issue a single call: 


Am, GpiPolyLine(hPS, count, &points); 
where 
om, ; : 

aPS is the Presentation Space Handle 
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count is a long value representing the number of points to draw. 
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& points is the pointer to an array of POINTL structures representing\__ 
successive (x, y) coordinates. 


Similarly, you can mark all the points in such an array using the 
GpiPolyMarker(hPS, count, &points); 


call. 


Using the Polyline in a Buffered Display 


6606000 


If you create an array of POINTL values for drawing in succession and use 
the GpiPolyLine call to draw all the lines at once, it can be as much as 50% 
faster than a series of individual GpiMove and GpiLine calls. If we create a 
packed buffer of data points as above where each vertical line represents the(__ 
maximum excursion of all the data points that would be drawn at that hori-, 
zontal pixel location, we can pass this array directly to the GpiPolyLine call. | 
Now, since these lines are drawn from successive points, rather than 
from bottom to top each time, we must arrange for our buffer to draw one\__ 
line “up” and the following one “down,” to minimize screen drawing time. 


This can be done easily with the following code: pd 
WinQueryWindowRect (hWnd, &rc /*get the window size “*/ pt 
pts per bin = (float)XDIM/(float)rc.xRight; Y 
j = 0; | & 
leftpnt = 0.0; /*fill the buffer with “*/ 
up = TRUE; /*mins and maxes a Y 
oldmin = 0; /*remember last */ WY 
oldmax = 0; /*min and max a & 
xp =O; | 
rightpnt = pts per bin; /*size of one bin sf 
while(rightpnt < XDIM) YL 
begin 7 } 
min = 10000; /*find max and min *] 
max = -10000; /*in each group */ @ 
for (i = (int)leftpnt; i < (int)rightpnt; i++) | 
begin 


if (max < x[i]) then 
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mm max = x[i]; /*find current max By 
| if (min > x[i]) then 
Oo min = x[i]; /*and min ag 
am end 
if (min > oldmax) then /*make sure this min 7, 
Oo min = oldmax; /*is not > old max ay 
ime if (max < oldmin) then /*make sure this max ar | 
max = oldmin; /*is not < old min ny 
“ oldmax = max; /*remember this min and */ 
“) —oldmin = min; /*max for next column “*/ 
om if (up) then 
| begin 
om butfer[j]sx = xp; /*draw up from min to max”/ 
am buffer[ j++].y = min; /*put min & max in buffer*/ 
buffer|[ j]«x = xXptt; 
o buffer[ jt+].y = max; 
Pin up = FALSE; /*next one is drawn down */ 
end 
“ else 
om begin 
- buffer[ j].x = xp; /*draw down from max to min*/ 
buffer[ j++].y = max; /*put min and max in buffer*/ 
me buffer[ j].x = xpt+; 
am buUTTéer| PrP} .y = mini | 
| up = TRUE; /*next one is drawn up of 
oO end 
mm, leftpnt += pts per bin; /*go on to next 3 
rightpnt += pts per bin; /*group of points a 
a“ end 
a™bufmax = j - 1; /*remember size of buffer */ 
Then the PAINT routine is just the simple call 
case WM PAINT: 
hPS = WinBeginPaint(hWnd, (HPS)NULL, (PWRECT)NULL) ; 
WinQueryWindowRect (hWnd, &rc); /*get current window */ 
/* dimensions i 
WinFillRect(hPS, &rc, CLR BLACK); /*fill it with black */ 
GpiSetColor(hPS, CLR WHITE); /*draw white lines “*/ 
j = 0; 
GpiPolyLine(hPS, bufmax, buffer); /*draw entire xf 
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WinEndPaint(hPS) ; /*end paint routine */ 


break; 


DRAWING CLOSED FIGURES 


/* poly line ag 


800000 @ é 


There are three types of figures that you can draw as closed shapes using 


simple Gpi calls: boxes, arcs, and areas. The simplest of these is drawn by 
the GpiBox command, which simply draws a box whose lower left corner is\_) 
at the current drawing point, and whose upper corner is at the point defined’ ) 


in the call 


where 


hPS 


control 


& pt 


hround 


vround 


If either rounding parameter is NULL, the corners are not rounded. 


DRAWING AN ARC 


WY 
GpiBox(hPS, control, &pt, hround, vround); 

WY 
is the Presentation Space Handle. WV 
defines whether the box is to be filled, using the con-\Ww/ 
stants DRO_FILL, DRO_OUTLINE, on 
DRO_OUTLINEFILL. DRO_OUTLINEFILL. Cc 


contains the coordinates of the diagonally opposite box 
corner. 


@ < 


is the horizontal length of the full axis of the ellipse used 
for rounding the corners. 


e< 


is the vertical length of the full axis of the ellipse used 
for rounding the corners. 


60006 


An arc is an ellipse or a segment of an ellipse and can, of course, include thé/ 
circle. The shape of the ellipse is defined by an ARCPARAM structure con{_) 
sisting of two points on the edge of the ellipse, which produce perpendicular 
lines when drawn to the center of the ellipse. The structure consists of two 


(x, y) coordinate pairs called (p, s) and (r, gq). The structure has the form 


WY 
& 
UU 
VY 
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typedef struct _ARCPARAMS 


t 

LONG IP; 
LONG 1Q; 
LONG IR; 
LONG 1S; 
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} ARCPARAMS ; 


©) The default settings for these parameters produce a circle whose center is 
™) the drawing point (p=1, r=0, s=0, q=1). Thus, if you do not change the arc 
@ Parameters, the GpiFullArc call will draw a circle. This call has the form 


am GpiFullArc(hPS, control, multiplier); 
“> where 
©) control is DRO_FILL, DRO_OUTLINE or DRO_OUTLINEFILL 


“% multiplier is a fixed point fraction that determines the size of the arc. The 
“a largest allowed multiplier is 256. 


©) The fixed point fraction can be constructed using the MAKEFIXED macro, 
™) where the first argument is the fixed point part and the second argument the 
> fractional part. A typical call to draw a 20-pixel ellipse would be 


om  GpiFullArc(hPS, DRO_OUTLINE, MAKEFIXED(20,0)); 
™) It is also possible to draw partial arcs, using the call 


GpiPartialArc(hPS, &center, multiplier, start, sweep); 


where 

& center is a POINTL structure describing the coordinates of the 
arc center. 

multiplier is a fixed point fraction that determines the size of the 


arc. The largest allowed multiplier is 256. 
start is the starting angle as a fixed point fraction. 


sweep is the sweep angle as a fixed point fraction. 
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Pattern Filling 


Boxes, full arcs, and areas are filled with the current pattern if DRO_FILL~’ 
is set. If you do nothing, this is a solid fill pattern. However by using the\_» 
call 


PATSYM_DENSE] - PATSYM_DENSE8 


COLORS 


ww 
GpiSetPattern(hPS, pattern); C) 
you can set the current pattern to one of the following: WS 
\/ 
PATSYM_DEFAULT PATSYM_DIAG4 

PATSYM_VERT PATSYM_NOSHADE Y 
PATSYM_HORIZ PATSYM_SOLID WwW 
PATSYM_DIAG1 PATSYM_HALFTONE VU 

PATSY M_DIAG2 PATSYM_BLANK 
CG 
WY 


OS/2 PM defines 16 different colors that correspond to the same colors(_) 
available on the original PC color graphics adapter in character mode. Youg \ 
can set the current color for text, lines, markers, and areas using the 
GpiSetColor call 


GpiSetColor(hPS, color); 


where color is one of the following: 


CLR_WHITE CLR_DARKGRAY 
CLR_BLACK CLR_DARKBLUE 
CLR_BLUE CLR_DARKRED 
CLR_RED CLR_DARKPINK 
CLR_PINK CLR_DARKGREEN 
CLR_GREEN CLR_DARKCYAN 
CLR_CYAN CLR_BROWN 
CLR_YELLOW CLR_PALEGRAY 


CLR_NEUTRAL 
The following special values for color settings can also be used: 
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™, CLR_FALSE all bit planes are zeroes. 
) CLR_TRUE all bit planes are ones. 
Oo CLR_DEFAULT The device-dependent color that contrasts with its 
om natural background. 


)\CLR_BACKGROUND The device’s natural background color. 


“ You can also set each of the primitive types (line, character, marker and 

area) to have their own independent color values using the GpiSetAttrs call, 

om where you can set a mask so that the basic color is only changed for one of 
these types at a time. This is usually more programming than it is worth and 
we will not use it here. 


mo 
m 
— FILLING AREAS 
om 


™) An area is a section of the drawing that starts and stops with commands you 
insert in the drawing sequence. You can fill an area regardless of shape by 
starting it with the GpiBeginArea call, drawing some lines, and then closing 
_ /the area with the GpiEndArea call. If the area is not a closed figure, the 
close area call draws a line back to the beginning of the area to close it. The 
amy calls for starting and ending an area are 


Pia’ GpiBeginArea(hPS, options); 
5 GpiEndArea(hPS) ; 
where 

oa 

a eons can be BA~TNOBOUNDARY or BA_BOUNDARY to 
draw boundary lines or not, and BA_-ALTERNATE or 

om BA_WINDING to define whether to construct the inte- 

a, rior by the number of boundary crossings or not. 


6 The following calls draw a filled equilateral triangle: 
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GpiBeginArea(hPS, BA ALTERNATE); /* begin area for filled” 
* triangle : 


~ set first vertex 


j 

“s 
GpiMove(hPS, &pos); a 
pt.x = pos.x + BOXWID; / 
/ 
/ 


pL.y¥ = pos.¥; 


/ 

/ 

/ 

/* move across x 

j 
GpiLine(hPS, &pt); /* draw line across base 

/ 

/ 

; 

/ 

/ 

/ 


J! 
-! 
| 


r wv 


lo 


. 
x. 
U 
7 
1 
v 
1 


leave y the same 


— - 


i 


“ for apex ° 
wl a 


‘ altitude == width 
* altitude 
* draw last line 


wl 
aw 


pt.x = pt.x - BOXWID/2; * back up x halfway ‘ 
pt.y = pos.y + BOXWID; 
GpiLine(hPS, &pt); * 
GpiLine(hPS,&pos); 
GpiEndArea(hPS) ; 


1. 
x 


si 


f 
‘ 


/ 
/ 
/ 
/ 
/ 
/ 


fill area of triangle’ 
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PATHS AND LINE WIDTHS 


There are analogous calls to start a drawing region called a path. A path. 


e« 


can be used just like an area, to define a part of the screen to close and fill, 


C 


but it is more often used to define a series of lines and curves that-have a 
width greater than a single pixel. The call GpiSetLineWidth described in |_| 
the reference manual has no effect in OS/2 PM 1.2 and is included for , 


( 


future expansion. However, the call 


@o¢ 


GpiSetLineWidthGeom(hPS, width); 


has an effect when describing the drawing of a line or lines inside a path. In ¢ \ 
the current implementation of OS/2 PM, there can be only one path at a 

time and the calls to refer to that path always reference path number IL. Y 
Once the path has been opened, you can issue any of a number of drawing \/ 
commands. At the end of the group of drawings, you close the path and &J 
issue the GpiModifyPath call to indicate that wide lines are to be drawn, fol- 

lowed by the GpiFillPath command to fill the lines to this width. The fol- Y 
lowing code draws a thick line and a thick box. | 
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mm GpiSetLineWidthGeom(hPS, 4L); /*set 4 pixel wide line*/ 
GpiBeginPath(hPS, 1L); /*begin the path */ 
~ /GpiMove(hPS, &pos); /*move to first point “*/ 
@)Gpiline(hPs, ept); /*draw a line to 2nd pt*/ 
GpiMove(hPS, &pos); /*move to start of box */ 
~ /GpiBox(hPSs, DRO OUTLINE, &pt, 
Oo NULL, NULL);  /*draw the box */ 
em GpiEndPath(hPS) ; /*end the path at 


/* set up for wide lines “/ 
O)GpiModifyPath(hPS, 1L, MPATH STROKE); 
em GpiFillPath(hPS, 1L, FPATH WINDING); /* fill the path  */ 


om 
ERROR CHECKING OF GPI CALLS 


‘Many Gpi calls do not return error codes but instead return other values of 
Muse in advanced programming. If you have a programming problem you 
want to debug, the WinGetLastError call is useful. 


Myerr = 
a WinGetLastError(hAB); /*see if there has been an error’/ 
if (err != 0) then 


“sy begin 

Mm  sprintf(buf, ‘Error = ox! ered: forint it te buffer*/ 
WinMessageBox(HWND DESKTOP, 

Oo“ hWnd, buf, Graphics error’; 

am, 1, MB OK); /*and put in message box™/ 

- end 


am To use it, you need the handle to the anchor block. If you debug using 
Codeview or print out the error value in hexadecimal in a message box you 
‘can look up the error number in the pmerr.h file. 
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©) One of the great advantages of OS/2 Presentation Manager is its ability to 
™) spawn a number of tasks and have each one associated with a visual indi- 
a cator in its own window. Windows created by other windows are known as 

child windows. We have already seen a number of examples of child 
©) windows in dialog boxes, where all of the symbols representing various types 
©) of boxes are actually child windows preprogrammed to behave in standard 


am Ways. 
o 
o, USES OF CHILD WINDOWS 


a, 


Child windows can be used to represent events taking place in separate tasks 
©) or to show information in different ways. For example, in a data acquisition 
om program you could show the data being acquired in a child window while 
_ maintaining the main window for processing of user commands. Another 
common use of child windows is to allow the user to view data in a number 
) of ways at the same time. For example, you might want to see data in both 
«™» graphical and tabular form in two windows, and see how changing the data 
yr in one window affects the display in the other. 


155 
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CREATING CHILD WINDOWS 
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Creating child windows is just as easy as creating the main window. 
However, it is customary to create child windows as “invisible” and then use \_/ 
the WinSetWindowPos function to make them visible at a position chosen by; 

the program, rather than letting PM decide on default positions. Each child... 
window must have its own window procedure and each procedure’s name — 
must be declared in an EXPORTS statement in the .DEF file unless you~’ 


compile with the /A/fu compile switches. &/) 
INSTANCES OF THE SAME WINDOW ¢ 


J 
—* 


Now we are going to draw two small windows on the screen that have iden- 
tical properties, except that one will be drawing a blue line and one a red“ 
line. Further, they will be drawing these lines at different rates, since we are\__ 
sending timer messages at different frequencies to the two windows.” ) 
However, there is now reason to clutter up our program (and memory) with 
two virtually identical window procedures for drawing red lines and blue 
lines. Instead, we can register the class of one single window type and create\_ 
two windows of that class. | 
The only problem we will then have is telling from within the window 
procedure which color we are supposed to draw and where the current line isV 
located. We will store the current color and line position in a structure\y 


pointed to by the extra bytes associated with each window. & 
YW 
THE CHILDREN PROGRAM Ly 


To illustrate the uses of child windows in a multitasking environment, we 
will write a program to display two small child windows. Then we will start 
two timers ticking at different rates, and have the timers send their “ticks”\_) 
to the two windows. Whenever a window receives a tick, it will draw a line, 

one pixel further to the right, and when the window is full horizontally, it 

will begin drawing from the left two pixel rows higher. To illustrate the 
ability to open and close windows, we will use two menu commands: one to\_) 
turn on the windows, and one to destroy them. 
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In this program, the “tasks” are the timers themselves. The child 
windows all run as part of the main program, receiving messages asynchro- 
nously from the timer tasks. 


98300000 
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Creating the Main Window 


om Creating the main window is exactly like creating the windows we have used 

previously, except that it is important that the style _ bit 
© CS_CLIPCHILDREN be set when the class is registered. This tells PM 
() that children of this window are not to be painted over when the main 
() window is repainted. 


) /*register the main Window class*/ 
™ WinRegisterClass (hAB, 


(PCH)szClassName, 

(> (PFNWP)TimerWndProc, 

(™ CS _SIZEREDRAW |CS_SYNCPAINT | CS _CLIPCHILDREN, 
O35 

- Likewise, you must register the class of the child windows: 

‘ile WinRegisterClass (hAB, /*child window class at 
"Children'', /*class name = 
ChildiWndProc, /*window procedure a 

NULL, 
6 ): /*space for pointer and color value*/ 
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~ The Child Window Procedures 
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om Since both child windows do the same thing, their window procedures are 
» identical, except that we draw one line in red and one in blue for contrast. 
They must interpret the WM_TIMER message that is received each time 

™ the timer ticks, and draw the line one pixel further. In order to tell which 
ie) window we are currently executing, we need a way to pass arguments to 
™ each child window indicating the current line position and color. We do this 
io by using the “extra bytes” feature of windows. When we register the class of 
the child window, we reserve 4 bytes for a pointer to a POINTL structure 

’ containing the current line coordinates and 2 more bytes containing the 
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color of the line. Then, when we start these windows, we will put values in 
these extra bytes. 


Starting the Timers 


The timers can be started in a windowing environment using the call 


WinStartTimer(hAB, hWnd, tid, time); 


©0060 8088008000< 


where 
hAB is the handle to the main window’s anchor block.. 
hWnd is the handle of the window to which the timer ticks are 
to be sent. 
tid is the timer id number: an arbitrary small integer below baad 
the value TID_USERMAX. WY 
time is the time in milliseconds between timer ticks. Ww 
Note that this WinStartTimer function eliminates the need for semaphores aed 
and for the DosTimer function. WY 
&) 
Passing the Arguments to the Window Procedures Y 


When we start the child windows, we use the usual WinCreateStdWindow. 

call, referring to both windows by the same class name “Children.” Then, 
immediately after the call, we set values into the extra window words using 
the WinSetWindowULong and Ushort commands. CY 


WinSetWindowULong(hWnd1, 0, &redpnt); /*pass the pointer*/ \J 


WinSetWindowUShort(hWnd1, 4, CLR_RED); /“amd the color “*/ & 


It is important to recognize that the WM_CREATE message is executed(_) 
before the program returns from the WinCreate call, and therefore the argu-, 
ments are not yet there. Thus, we cannot access them during 
WM_CREATE but only later when the window is visible. In this case, since 
there are actually two instances of the same window in operation, we cannot\_| 
store these values in local static variables, but must request them from the, 
window words each time we need to draw another pixel. 
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“) Drawing the Pixels at Each Timer Tick 


Note that in order to keep the example simple, these child windows do not 
have a paint procedure, and if you decide to move or size the child windows, 
the line will not be redrawn from the beginning: 


IO 


©) MRESULT FAR PASCAL ChildWndProc(HWND hWnd, USHORT msg, 


A, MPARAM mp1, MPARAM mp2) 

D begin 

om, POINTL “point; /*pointer to point structure if 
~~ int color; /*and color obtained from extra bytes*/ 
©) switch (msg) 

am, begin 

™) case WM ERASEBACKGROUND: = /*tell PM to erase screen*/ 
Amy return(TRUE) ; 

break; 
am, 
am case WM TIMER: /*draw new point on each tick*/ 
point = 

a“ (POINTL *)WinQueryWindowULong(hWnd, QWL USER); 
o color = 

om (int )WinQuer yWindowUShor t (hWnd, QWL_USER+4) ; 

incrline(hWnd, point, color); 
Oo break; 
om, 
default: 

om return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
am break; 

~ end /*switch*/ 

orn t- is 

-return(OL); /*message not processed”*/ 


Mend /*child*/ 


Each child window must also. receive and interpret the 
am WM_ERASEBACKGROUND message since it is not doing any painting, 
and must return TRUE, which tells PM that it must erase the window’s 
background. This message is sent whenever the child window is resized by 
) the user. 


om 
rw 
on, 
o~ 
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Drawing the Lines in the Windows 


© ¢ 


The incrline function is called by the timer routine and draws a line across 
the screen a pixel at a time. For it to begin drawing, it must obtain a micro ‘ 
presentation space using the WinGetPS function, and release it when done. 


< 


hPS = 
WinGetPS(hWnd) ; /*get presentation space handle*/ 
GpiSetColor(hPS, color); /* set the current color “y 
IpPoint->x++; /* increment the line length “*/ 
if (lpPoint->x > XMAX) then /” if the line is: at the */ 
begin /* end of the window ey 
IpPoint->x = 0; /* reset the x-value my 
IpPoint-7y += 2; /* and move up two lines */ 

end 


/* set that pixel “/ 


release PS jf 


GpiSetPel(hPS, (PPOINTL)1IpPoint) 
WinReleasePS(hPS) ; 


Closing Child Windows 
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Just as you destroy the main window when your program terminates, you 
can destroy child windows when you are through with them. You simply use 
the call 


e< 


WinDestroyWindow(hWndchi 1d1Frame) ; 


where the window you actually destroy is the frame. The client window is a 
child of the frame and is destroyed automatically when its parent is\_ 


destroyed. Y 
a, 
THE FINAL PROGRAM Y 


When the program is run and the “Start’’ command selected, the two child Y 
windows appear as shown in Figure 11-1. 
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Children 


Commands 


DALI ALAALAALAAASLS. 





, Figure 11-1. A display from the CHILDREN program 
ao 


) They disappear when “Stop” is selected. Note that since the timers run as 
om, Separate tasks, you always have access to the menus. 


J. Ie i ot A ol. IN PN 
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om /* ‘“PM program with child windows and timer 
#define INCL BASE 
)#define INCL PM 
O™) #include <os2.h> 
#include <cdefs.h> 
-#include <string.h> 
) #include "'childefs.h' 


oo 

sy 

mm #define XMAX 100 

im, tdefine SWP SWP_SIZE | SWP_MOVE | SWP_ACTIVATE | SWP_SHOW 

‘ )MRESULT FAR PASCAL ChildWndProc(HWND hWnd, USHORT msg, 
MPARAM mp1, MPARAM mp2); 


MRESULT FAR PASCAL ParentWndProc(HWND hWnd, USHORT msg, 
MPARAM mp1, MPARAM mp2); 


HAB hAB; /*handle to anchor block*/ 


) 
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POINTL bluepnt, redpnt; 


wb wb wb wb ob 
i 


a 
. 


seek kkk Iw wb ot. sh Jb wb 


’ IN IN IN NON ON Wawa M a i n F unc { j on PRIN ION IN ONS 
int cdecl main () . /*C main routine at 


begin /* as before”/ 
end 


wl wb ow ob ob oe 
| ia IN IN ONAN IN ONIN IN ONIN IN IN IN IRIN NINN INNS 


void incrline(HWND hWnd, PPOINTL IpPoint, USHORT color) 


ale J oe I 
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lo ~ 
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aL 
cay 
cay 


/* increments line to new position in either child window*/ 
begin 

HPS WPS; 

CHARBUNDLE cb; 


hPS = WinGetPS(hWnd); /* get presentation space handle “/ 
GpiSetColor(hPS, color); 
IpPoint->xt+; 
if (IpPoint->x > XMAX) then 
begin 
IpPoint->x = 0; 
IpPornt=>y += 2; 
end 
GpiSetPel(hPS, (PPOINTL) 1pPoint); 
WinReleasePS(hPS); 


I we we Ie we Ie I I 
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MRESULT FAR PASCAL ChildWndProc(HWND hWnd, USHORT msg, 
MPARAM mp1, MPARAM mp2) 


s- 
cay 


begin 
POINTL “point; /*nete that this. is statics 
int color; 


switch (msg) 
begin 


case WM ERASEBACKGROUND: /*tell PM to erase screen*/ 
return( TRUE); 
break; 
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case WM TIMER: /*draw new point on each tick */ 
point = (POINTL *“)WinQueryWindowULong(hWnd, QWL USER); 
color = (int)WinQueryWindowUShort (hWnd, QWL_USER+4) ; 
incrline(hWnd, point, color); 
break; 


default: 
return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
break; 
end /*switch*/ 
™yreturn(0L); /*message not processed” / 
end /*child*/ 


DAAAAAAALSAS 
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* ° . * 
(/* Main window procedure for all messages / 
RRR RR RK a RRR RR RRR RRR RRR RE RS RRS 
MRESULT FAR PASCAL ParentWndProc(HWND hWnd, USHORT msg, 
‘i MPARAM mp1, MPARAM mp2) 
begin 
‘ili * : * 
HPS hPS; /“handle to presentation space”*/ 
* : * 
RECTL re: /*rectangle for paint j 


| ULONG flCreate; 

” HWND hWnd1, hWnd2; /*child window handles 
o static HWND 

hWnd1Frame, hWnd2Frame; /*child window frames*/ 


slp 
«N / 


‘i. 
switch (msg) 
ambegin 
case WM COMMAND: /*jnterpret menu commands i 
switch(LOUSHORT(mp1)) /*in lower word of mp1 a 
begin 
/*“open 2 new windows and set timers i 
case STARTTIME: 
flCreate = FCF _TITLEBAR | FCF SIZEBORDER | 
FCF MINMAX; 
bluepnt.x = 0; /*“initialize pointers a 
bluepnt.y = 10; /*for drawing ar 


redpnt.x = 0; 
redpnt.y = 10; 
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CHILD WINDOWS 


hWndiFrame = WinCreateStdWindow( hWnd, 


FS BORDER, 
&flCreate, /*control data */ 
Children’, /“window class */ 
on Pe /*window title */ 
(ULONG)NULL, 
(HMODULE )NULL , 
2; 
&hWnd1); /*client area handle*/ 
/*pass the pointer*/ 
WinSetWindowULong(hWnd1, 0, &redpnt); 
/*and the line color*/ 
WinSetWindowUShort(hWnd1, 4, CLR RED); 
hWnd2Frame = WinCreateStdWindow(hWnd, 
FS BORDER, 
&f1Create, /*control data */ 
Children’, /*window class */ 
Haga! /*window title “*/ 
(ULONG)NULL, 
(HMODULE)NULL, 
3, 
&hWnd2) ; /*client area handle*/ 


WinSetWindowULong(hWnd2, 0, &bluepnt); /*pointer”/ 
WinSetWindowUShort(hWnd2, 4, CLR BLUE);/*color “*/ 


WinSetWindowPos(hWnd1lFrame, HWND_ TOP, 
100,100,100,100,SWpP) ; 
WinSetWindowPos(hWnd2Frame, HWND TOP, 
300,100,100,100,SWP); 


WinStartTimer(hAB, hWnd1, 

4, 200); /*start 2 timer threads “*/ 
WinStartTimer(hAB, hWnd2, 

5, 300); /*sending ticks to windows*/ 
break; 


case STOPTIME: /*destroy the 2 child windows*/ 


WinDestroyWindow(hWnd1Frame) ; 
WinDestroyWindow(hWnd2Frame) ; 
break; 
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oo 
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on 

m 

m default: 
return(WinDefWindowProc(hWnd, msg, mpl, mp2)); 

om, end 

lia’ break; 

case WM ERASEBACKGROUND: 

ma return( TRUE) ; /*message is processed*/ 
break; 

im 

a ycase WM PAINT: 


hPS = WinBeginPaint(hWnd, (HPS)NULL, (PWRECT)NULL); 


“ /*get current window dimensions*/ 
om WinQueryWindowRect(hWnd, &rc); 
> WinFillRect(hPS, &rc, 
| CLR BLACK); /*fill it with black */ 
Oo WinEndPaint(hPS) ; /*end painting routine*/ 
oo break; 
Mdefauit: 
Ay return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
> break; 
“Jend /*switch*/ 
mm, 
mreturn(OL); 
end 
~~, 
A, 


~The CHILDREN Resource File 


amit include "childefs.h'' 

POINTER HELLOWIND children.ico 

MENU HELLOWIND PRELOAD 
m™ BEGIN 

SUBMENU ''Commands'', HELLOCMD 
BEGIN 
am MENUITEM ''Start'', STARTTIME 
om MENUITEM ''Stop'', STOPTIME 
by END 

OYEND 


»@0@@ 
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12 Using the Mouse in OS/2 
Programs 


In many OS/2 PM programs, the mouse is the main method of communi- 


eo cating with the program. You use the mouse to select menu items, interact 


with dialog boxes, and point at program objects. To use the mouse in your 


Own programs, you need to intercept the messages that the mouse sends to 


the window it is moved over. These messages are 


“ WM_MOUSEMOVE 

ins 

o@ WM_BUTTONIDOWN 

am, VV M_BUTTONIDBLCLK 
WM_BUTTON2DOWN 

)WM_BUTTON2DBLCLK 

om WM_BUTTONIUP 


= N2UP 
| om WM BUTTO 


The mouse has moved over the current 
window. 

The left button has been pressed. 

The left button has been pressed twice. 

The right button has been pressed. 

The right button has been pressed twice. 
The left button has been raised. 

The right button has been raised. 


om in each case, mpl contains the x and y coordinates of the mouse position. 


om, 


a@A SIMPLE MOUSE ETCH-A-SKETCH 


_ The window procedure fragment that follows draws a line to the current 
©) mouse position each time the WM_MOUSEMOVE message is received. 
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case WM MOUSEMOVE: 


pt.x = SHORTIFROMMP(mp1); /* x and y coords a 
pt.y = SHORT2FROMMP(mp1); /* are packed in mp1 */ 
GpiLine(hPS, &pt); /* draw line to I 


/* new mouse position */ 
break; 
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Window Initialization 


To implement this simple procedure, we have to make a few changes in the 
way we have done things in the past. First, we are not doing our drawing 
from inside a WM_PAINT message, and thus we cannot usé_) 
WinBeginPaint. But, in order to have a handle to a PS to use for this simple 
drawing, we must create and keep a presentation space during the entire life 
of the window. This also gives us the chance to specify the color of the line 
only once, during initialization. We will also need to set the cursor position__ 
(pointer) to a known spot before we start. We make this part of our initial; 
ization as well, setting the pointer to (0,0) with the WinSetPointerPos call. 
Note that since we want to use the PS throughout the life of the window, it 


must be a static variable. Ty 

case WM CREATE: Y 

hPS = WinGetPS(hWnd) ; /*get cached PS ‘/ ©@ 
WinSetPointerPos(HWND DESKTOP, | 

0, 0) /*set pointer Fs Y 

GpiSetColor(hPS, CLR WHITE); /*and drawing color *“/ (>) 

break; f*keep it so we can */ 

/*draw on mouse moves*/ Y 

i, 

& 


The Paint Routine 


We do still need to process WM_PAINT messages, however, but only sq__ 
that the background will be completely cleared when we start. However 
since we are not using WinBeginPaint and WinEndPaint to start and finish 
our painting, we need to tell PM that we have now repainted the window and 
that it should remove further paint messages from the queue. We do thi¢__ 
with the WinValidateRect call, which removes the specified rectangular 
region from the window’s list of regions needing updating. 


Seee 
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case WM PAINT: 
- WinQueryWindowRect (hWnd, &rc); /*get current window “*/ 
/* dimensions - 
WinFillRect(hPS, &rc,CLR BLACK);/*fill it with black 
WinValidateRect (hWnd, 
&rc, FALSE); /*“remove paint messages” / 
break; 


»@d@ 


(Removing the Presentation Space 


) 


Whenever you have obtained a cached presentation space, or a normal PS, 
you must release it when the window is closed. This is done with the 
)WinReleasePS call when the window receives a WM_DESTROY message: 


case WM DESTROY: 
m@, WinReleasePS(hPS); /*release PS when window is closed*/ 
break; 


Releasing the PS is quite important, because OS/2 may begin behaving 
strangely if these PS’s are allowed to remain in use. The complete mouse 
window procedure is given below: 


mo 
MRESULT FAR PASCAL MouseWndProc(HWND hWnd, USHORT msg, 
on MPARAM mp1, MPARAM mp2) 
~ 
begin 
‘die Static HPS hPS; /*handle to presentation space “*/ 
am, RECTL. rey /*rectangle definition structure*/ 
) POINTL pt; /* point definition structure “*/ 
Mswitch (msg) /*interpret messages a 
begin 
rae 


Mycase WM CREATE: 

hPS = WinGetPS(hWnd) ; /*get cached PS */ 
~WinSetPointerPos(HWND DESKTOP, 

0, 0); /*set pointer sf 

a GpiSetColor(hPS, CLR_WHITE); /*and drawing color */ 

~ break; /*keep it so we can “*/ 

/*draw on mouse moves*/ 


J 


a! 


¢ 
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case WM MOUSEMOVE: 


pt.x = SHORTIFROMMP(mp1) ; /*x and y coords are ”* 
pt.y = SHORT2FROMMP(mp1); /*packed in mp1 a 
GpiLine(hPS, &pt); /*draw line to new . 
break; /* mouse position : 


case WM PAINT: 
WinQueryWindowRect(hWnd, &rc); /*get current window 
/* dimensions 
WinFillRect(hPS, &rc,CLR BLACK);/*fill it with black 
WinValidateRect (hWnd, 
&rc, FALSE); /*remove paint messages*/W 


a2 
wv 
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oA 
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cay 


BLERN: VL 
case WM DESTROY: wo 
WinReleasePS(hPS) ; /*release PS when window™/(_ 
break; /* is closed a 
Ww 
default: \s 
return( WinDefWindowProc( hWnd, message, mpl, mp2)); 
Y 
break; 
end /*switch*/ WY 
return(OL); bod 
end WY 
VL 
DRAWING LINES ON BUTTON PRESSES Y 


In our second example, we will set the beginning of a line segment the firg ) 
time the left mouse button is pressed, and actually draw the line when the 
button is pressed again. To do this we will have to set a flag that remembers” 
whether this is the first or second time the mouse button has been presset_/ 
Now, since each mouse message represents a separate call to the windo 
procedure, we cannot keep this flag as an automatic variable, but must mak- 


C 


it static so that its value will remain between calls to the window procedure.“ 


SCOedoe 
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M™nitialization 
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Jur initialization is quite simple: we must get a cached PS as before, set the 
_ iefault line color, and set the flag origin to FALSE to indicate that no line is 


(eing drawn: 

©) static BOOL origin; 
Fin 

OWwitch (message) 
amegin 


@ase WM CREATE: 
(Mm origin = FALSE; 
hPS = WinGetPS(hWnd); 


/*flag te indicate  “/ 


al 
/ a 


start of new line*/ 


/*interpret messages*/ 


/*button not pressed yet 
/*get cached PS 


' GpiSetColor(hPs, CLR WHITE); /*and drawing color 


M) break; 
om 
- 


@Drawing the Line Segments 


/*keep it so we can draw 
/* on mouse moves 


sh 
“Vy 


ss ™ “Sw. Si Sx, 


On this program, all of the action takes place when a WM_MOUSEMOVE 
message is received. If origin is not set, a new line is begun and a single pixel 
as turned on at the start of the line and it is set to TRUE. If origin is turned 

on then it draws a line and sets it back to false again. 


ase WM BUTTONIDOWN: 


pt.x = SHORTIFROMMP(mp1); /* 
™) pt.y = SHORT2FROMMP(mp1);  /* 
a if (origin) then 
begin 
©) GpiLine(hPsS, épt); 
origin = FALSE; 
end 
else 
begin 
GpiSetPel(hPS, &pt); 
GpiMove(hPS, &pt); 


origin = TRUE; 
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/*draw line to new mouse 


aL 
/ rk 
al, 
/’ 


‘indicate line is done 


} 


‘show start of next line 
ia 


‘set drawing point locn 
/*indicate new line starting’ 


x and y coords are 
packed in mp1 


position 


aL 
we 
al 
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end 
break; 


MOVING OBJECTS ON THE SCREEN WITH THE 
MOUSE 
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One of the most easily understood program features for a new user is the 
ability to move objects around on the screen using the mouse. If the object is 
very simple, such as the box in the program below, it is acceptable to erase 
and redraw the entire object each time the mouse message is received. In) 
more complex cases, you might want to draw a rectangle around the object 
that moves with the mouse and only redraw the object when the final posi- 
tion is determined. WY 
In this example program, a 100 x 100 white box is displayed on the) 
screen and moved around as the mouse moves. This movement is accom-¢ \ 
plished by setting the drawing mode to exclusive OR mode or XOR mode. 


‘ 


In this drawing mode, redrawing the same lines a second time erases them” 
from the screen. When the left mouse button is pressed, the program draws.) 
a filled red box at the current box position. Since the program continues, you 
can draw any number of red boxes on the screen with it. Of course, if the 


boxes overlap, the overlapping part will be black again, because the drawin ad 
mode remains as XOR. WY 

VY 
Initialization VU 


As in our previous examples, we will obtain a micro presentation space when 
the window is first created. We also need to set a flag drawn to indicate that 
the first box we draw can be drawn without erasing a previous one. WV 


static POINTL pt, ptcorner; /* point structures a7 Med 

static BOOL drawn; /*flag if one drawn yet*/ WwW 
switch (msg) /*interpret messages “*/ - 
begin | 


case WM CREATE: 
hPS = WinGetPS(hWnd) ; /*get cached PS 
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om 
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rr 
mm, GpiSetColor(hPS, CLR_WHITE); = /*and drawing color  */ 
GpiSetMix(hPS, FM XOR); /*set drawing mode 
oO /*to exclusive OR ~ 
M) WinSetPointerPos(hPS, 100,100); /*set pointer = 100,100%*/ 
> drawn = FALSE; /*no rect drawn yet se 
~ break; /*keep it so we can ss 
om /*draw on mouse moves “*/ 
am 


° 
=, 
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Then, each time a WM_MOUSEMOVE message 1s received, we erase the 


B-evious box and draw a new one at the new mouse position: 
Am, 
case WM MOUSEMOVE: 
©) if (drawn) then 
a, begin 
GpiMove(hPS, &pt); /*erase box in old position*/ 
fs ptcorner.x = pt.x + 100; /*set box size to 100x100 */ 
am picorner.y = pt.y + 100; 
GpiBox(hPS, DRO OUTLINE, 

Oo &Eptcorner, OL, OL); /*XOR out old box a 
om, end 
am Ptx= SHORTIFROMMP(mp1); /* x and y coords are ey 
“7 pt.y = SHORT2FROMMP(mp1); /* packed in mp1 a 
©) GpiMove(hPS, &pt); 
gm ptcorner.x = pt.x + 100; /*set box size to 100x100 */ 

ptcorner.y = pt.y + 100; 
©) GpiBox(hPS, DRO OUTLINE, 
ao, Eptcorner, OL, OL); /*draw in new box of 

drawn = TRUE; /*erase all future boxes as 
“Oo break; 


Boo that the GpiBox call uses the style DRO_OUTLINE to indicate that 
Only the outline of a box is to be drawn. The box is drawn at the current 
emrawing point specified by the last GpiMove or GpiLine, and is drawn so that 
nthe upper right corners are specified by the point structure in the argument 

ptcorner. Once we have drawn our first box, we set the drawn flag to TRUE 

0 that all future boxes are drawn after erasing the previous once. Note that 
o™he pt structure is static so that the previous position will always be remem- 


apbered. 
am 
a 
om 
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Drawing a Filled Box 


When the left mouse button is depressed, this program draws a filled red box 
at the current drawing point. This is done in just the same way as the\_ 
GpiBox calls above, except that the style argument is changed toE 
DRO_FILL. 


break; 


THE MOUSE POINTER: VISIBILITY AND 
ACCESSIBILITY 


a, 
case WM BUTTONIDOWN: 
GpiMove(hPS, &pt); /* move to current point / Y 
pt.x = SHORTIFROMMP(mp1); /* x and y coords are “| @ 
pt.y = SHORT2FROMMP(mp1); /* packed in mp1 */ & 
ptcorner.x = pt.x + 100; /*set box size to 100 x 100 */ 
ptcorner.y = pt.y + 100; WY 
GpiSetColor(hPS, CLR RED); /* fill box in red a YL 
GpiBox(hPS, DRO FILL, 
Eptcorner, OL, OL); /*draw in new box “| Ww 
GpiSetColor(hPS, CLR WHITE); /*reset color to white */ oe, 
WwW 
VY 
WY 
WY 


In our examples so far, we have done nothing to affect the mouse pointer on\_ 
the screen. Thus, in all of these examples, if the mouse pointer moves outside; 
the current window, messages will not be received and the drawing or box 
motion will stop. While this is often what you want, there are occasions in 
which you might not want to lose a mouse message or get a multistep series\Y 
of clicks and moves out of synch because the user has inadvertently moved(_) 
the mouse just beyond the window border. 

You can, however, capture all mouse messages to the current window by 


issuing the call Ww 
WinSetCapture(HWND DESKTOP, hWnd); /*capture mouse*/ Y 


where hWnd is the handle of the window that is to receive all the mouse — 
messages. Remember that once you do this, you have disabled all mouse 
pointer functions in other adjacent windows until you release the mouse. 
Issuing the same call with hWnd set to null releases mouse capture. 


SGedeort 
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The mouse pointer can be made visible or invisible using the 


las WinShowPointer call 
™,  WinShowPointer(HWND DESKTOP, FALSE); /*hide pointer™/ 
pod WinShowPointer(HWND DESKTOP, TRUE ); /*show pointer*/ 


a You must be careful, however, to be sure the pointer is turned back on 
before exiting from your program, since PM has no way of knowing that it 


‘should be turned back on if a process has made it invisible. 
ry 


ROUTING MOUSE MESSAGES TO SUBROUTINES 


As your programs begin to grow in complexity, it will become necessary to 
jo» interpret mouse messages in different ways depending on what function the 

user iS carrying out. This could lead to a rather convoluted structure in 
(which the action taken on mouse messages depends on which command was 
™) last selected. 
It is more desirable, however, to write subroutines or C functions in 
which a particular routine receives all the mouse messages for a given func- 
tion, and another routine all the messages for that function. This can be 
done in OS/2 PM programming by directing these messages to child 
a windows. These child windows are not some small section of the main 

window, but are in fact, identical with that window. Thus, by creating a 
-_/child window that has the same dimensions a the main window, you can send 
yall of the messages you wish to intercept to that window. 


om 


) Definition of the Mouse-Child Program 


We will write a program with a single menu item in a pull-down menu. This 

selection, “Box,” will cause the program to remove the cursor pointer and 
display a moving white hollow box much like the one above. When the 
em mouse button is pressed, the box will be filled with red and the cursor will 

reappear. To draw further boxes, the menu item must be selected again. 
o, In these examples, we will draw the moving box from within the child 
) window and draw a filled red box from within the child window. Then we 
@) will close the child window, but leave the red box on the screen. Since we 
will not be doing any drawing in the WM_PAINT routine, we will have to 


IDIO 


Ww 
WwW 
176 USING THE MOUSE IN OS/2 PROGRAMS Ss 
Ww 
prevent the screen from being erased when a paint message is received by ) 


the window. In this case, we will have to do this for both the child and the 
main window so that the main window does not erase the box just drawn by 


the child window. . ? 
VY 
User-Defined Messages Ww 


Since each window receives messages separately as calls from PM, we will 
have to tell the parent window not to repaint when the child window closes 
by sending it a message. The easiest way to do this is by defining a useky 
message NO_PAINT, which we send to the main window. PM has define) 
the constant WM_USER as the first message number not used by the 
system, and we can begin defining our own messages at this value. The fol- | 


lowing definitions make up the mouse4.h file: ae 
#def ine MOUSEWIND Y 
#define MOUSECMD 101 
#define MRECT 102 én 
#define NO PAINT ~ WM USER + 1 - 
We will also make up a simple menu in the resource file as follows: = 
Vl 11 wy 
#include mouse4.h 
POINTER MOUSEWIND mouse4.ico Y 
YY 
MENU MOUSEWIND PRELOAD Y 
BEGIN 
SUBMENU ''Commands'', MOUSECMD YY 
BEGIN f 
a, 
MENUITEM ''Box'', MRECT 
END VW 
END Ww 


This will cause a command bar to appear with the “Commands” header ant_) 
the drop-down menu containing “Box.” 
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Sending and Posting Messages to Windows 


There are two calls for getting messages to a window: 


WinPostMsg(hWnd, message, mp1, mp1); /*post a message*/ 
~ WinSendMsg(hWnd, message, mpl, mp1); /*send a message*/ 


A message that is posted is put into the message queue and will be received 
mn order from the main message dispatch loop. A message that is sent goes 
«™mmediately to that window and the call does not return until the message is 
ameceived and processed. In fact, WinSendMsg is equivalent to calling the 
window procedure directly. In nearly all cases, the WinPostMsg method is 
preferable, unless you have severe message timing constraints. 


om, 


ereating the Child Window 
Oo 
o create a child window having the same dimensions as the parent, we use 
the WinQueryWindowRect call to fill a RECTL structure with the current 
window dimensions. Then, we create a window having these dimensions 
sing the WinCreateWindow call. This call creates a pure window, without 
qmorder, frame, or title bar, and its existence as a separate logical window is 
pot apparent to the user. 


case MRECT: 

WinQueryWindowRect(hWnd, &rc); /*get window dimensions*/ 

©) WinCreateWindow(hWnd, /*child window same a 
‘'BoxWnd'', J" as main * / 

NULL, /* no text * / 

WS VISIBLE, /* make it visible oF 

(SHORT) rc.xLeft, /*position of window */ 

(SHORT) rc.yBottom, /* same as parent oF | 


(SHORT) (re.xRight - rc.xLeft), 
(SHORT)(rc.yTop - rc.yBottom), 


hWnd, /*parent window a 
HWND TOP, /*on top of parent y 
i; /*frame 1D * 
NULL, /* unused ar 
NULL); /*reserved a 
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Determining the Child Window’s Parent 


To send a message to the parent window, telling it not to erase the screen, we ww 
need for the child window to know the handle of its parent. This can be\__ 
done with the WinQuery Window call, which has the form 


& 
hParent = /*get handle to parent window*/ ? 
WinQueryWindow(hWnd, QW PARENT, FALSE); 

WinSendMsg(hParent, NO PAINT, YS 
OL, OL); /*tell it not to repaint a , 

The complete list of window handles this call will return is WwW 
QW_NEXT The window below the current window. Y 
QW_PREV The window above the current window. Y 
QW_TOP The topmost child window. pn 
WY 

QW_BOTTOM The bottommost child window. © 
QW_OWNER The owner of the window. LY 
QW_PARENT The parent of the window. , 


QW_NEXTTOP The next window in the owner window hierarchy 
which is subject to z ordering. 


¢ 


To further clarify this, the parent window restricts the movement of a child\_> 
window to its size, while the owner window is the one that receives messages, 
from the child. In many cases these are the same relationship, but for dialog 
box controls they could be different. 


Hiding the Pointer 


©6064 


It is not particularly elegant to have the mouse pointer showing when the 
box is being moved around on the screen, so the pointer is hidden when the 
child window is opened and shown again when the pointer is destroyed. 


C 
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The Complete Mouse-Child Program 


a 
fe 
a 
A 
v 

A 


cay 
aL 
“v 
YA 
“v 
. 

“ 
u 
cay 
u 
cay 
s 


/®REEKEE MOUSE 4 -- Mouse-Child Window Program **** / 
O)/* Moves a rectangle around on the screen, and fills it “*/ 
a’ with red when the left button is clicked. / 

, 


I ote te I I I I I I I sc PN a 
/* WN IN IN AN IN AININ IN 


>t 
AL 
cay 
aL 
cay 
aL 
cay 
aL 
cay 


AN EN AN AN AN AN AN AN IN IN AN IN IN AN IN IN IN IN IN IN AN UN EN IN AN AN UN EIN AN AN AN AN IN AN AN IN AN AN IN IN IN ING 


O#define INCL PM 

My #include <os2.h> 
#include <cdefs.h> 

o ° 11 V1 

#include mouse4.h 


sh oe ob LL 3 ale ole oe oe ee I I 0 
[RARKE IN ANIN ANON N WN ICAI TCI Th Th ae RTE AN OIE FEN TEIN PEIN IS SON INN ERIN EN THIN CAN TNYS EN TON PEE CM WS 


RESULT FAR PASCAL MouseWndProc( HWND, USHORT, 
! MPARAM, MPARAM ); 
O MRESULT FAR PASCAL RectWndProc( HWND, USHORT, 
ma MPARAM, MPARAM ); 
void draw box( , PPOINTL pt, int mode, int color); 


whe J J I sc se we sc she sk sc sk sk sie J sc sc sk sc sk sc sc eh Je ee ee ee sc sk 
Uf POETS RIS ERNE ES TEER OP MAUR RARE Se eNY Ps aw aN awa NIN IN AN IN AN IRIN IN INNINGS “f 


In we ot oI oI IL IL I. LL oe I I sc ‘ . IN RP DN PN EE oS a OE a oS 
mam FSIS IN IN TS FS FSS ON OS OS SN KS a j n F u n Cc t O gay SESS OS RN aS BNO RRARKE 
ale Je J ee I i I I sc 3 sc sk a Pn a sk sk sc sc sk sc sk sk sc sk NN DN a DE a eS si a sc sk al 
[BEBRRRERARRERRE RARER RE REE WNL IN ANN IN IN GN INN IN IN IN IN ONIN mcd? 


void cdecl main () /*C main routine*/ 


- 
a@yregin 

QMSG qmsg; /*defining a message queue “/ 
©) HAB hAB; /*handle to anchor block “*/ 
ay HMQ hmqMouse; /*handle to message queue “*/ 
o 
o 
a, 


2 


HWND hWnd; /*client area window handle*/ 
HWND hFrame; /*frame window handle a 
ULONG flCreate; /*“window create flag bits “*/ 


sh 


hAB = WinInitialize (NULL); /*init and get anchor handle*/ 
MyhmqMouse = WinCreateMsgQueue(hAB, 0); /*create msg queue */ 


/*register the Window class*/ 
OWinRegisterClass (hAB, /*handle to anchor block ‘ 
‘Mouse, /*name of window class ; 
MouseWndProc, /“address of window procedure” 
CS SIZEREDRAW, /*use these flags . 
ae ie /*number of ‘extra bytes 
WinRegisterClass (hAB, /*handle to anchor block 
''BoxWnd'', /*name of window class 
RectWndProc, /*“address of window procedure” 


5OS 
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sh 
ry 


ececeoeeooesc 


CS SIZEREDRAW, /“use these flags 
i /*“number of ''extra bytes 


flCreate = FCF _MINMAX | FCF SIZEBORDER | FCF SYSMENU 
|FCF_TITLEBAR | FCF SHELLPOSITION | FCF_ICON | FCF MENU; 


/*create the window */ 

hFrame = 
WinCreateStdWindow( 
HWND DESKTOP, /*as child of the desktop window"/ ( ) 


WS VISIBLE , 
&flCreate, /*control data bits 7 
‘Mouse, /*this name refers to class’ ‘/ @ 
‘'Mouse 4", /*title across top bar at a 
WS VISIBLE | WS _CLIPCHILDREN, Y 
NULL, /*menu is in resource file */(\) 
MOUSE ICON, /*frame identifier a 
&hWnd) ; /*client area handle Tid 
Ww 
/*get messages from the input queue and dispatch them /@ 
while ( WinGetMsg( hAB, &qmsg, (HWND)NULL, 0,0) ) | 
begin VW 
WinDispatchMsg(hAB, &qmsq); dy 
end : 
WY 
/* once the program is over, “7 Vy 
/* destroy the window and message queue */ 
WinDestroyWindow(hFrame) ; Y 
WinDestroyMsgQueue(hmqMouse) ; / 
WinTerminate (hAB); oe 
end 
Dae rae capt epee ge eee eT amen rene sil ai REA a 
/* The window procedure receives messages and acts on Jo 


/*them or passes them on for default processing. 
/*The only important command it receives is MRECT under /@ 
/*WM COMMAND which opens a child window to receive mouse "/@ 


/*motion messages. It also receives the user-defined are 
/*command NO PAINT which prevents repainting of the main Tad 
/*window when the child window closes */@ 
fer Did si < oid sk sk sk sc sk sc sc sk sc sc sk sk sk sc sk sc sk sc sc pie sk sc sc sc sk sk 3‘ sk sc sc 3 sc pid sk sk sc sc 3 sc Did sk sc sk sc sc sk sk sc sc sk sc * 


MRESULT FAR PASCAL MouseWndProc(HWND hWnd, USHORT msg, 


eccoe 
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ALLS. 


MPARAM mp1, MPARAM mp2) 


resin 
ar HPS APS: /*“handle to presentation space “*/ 
= RECTL Fes /* rectangle definition structure*/ 
M)switch (msg) /*interpret messages a i 
apes in 


Mycase WM PAINT: 
> hPS = WinBeginPaint(hWnd, (HPS)NULL, NULL); 

~ WinQueryWindowRect (hWnd, &rc); /*get Ajene tones? 
©) WinFillRect(hPS, rc, CLR BLACK); /*fi1l with black */ 
M) WinValidateRect(hWnd, &rc, 


pol TRUE);  /*remove paint messages*/ 
| WinEndPaint(hPS) ; /*end paint routine*/ 

OO) break; 

om 


case NO PAINT: 
OS WinValidateRect(hWnd, &rc, 
TRUE);  /*remove paint messages*/ 
break; 


IO 


acase WM COMMAND: 
switch(LOUSHORT (mp1) ) 
begin 
case MRECT: 
WinQueryWindowRect(hWnd, &rc); /*get dimensions “*/ 
WinCreateWindow(hWnd, /*child window same as main*/ 


‘'BoxWnd', 

NULL, /*no text oF 
WS VISIBLE, /*make it visible */ 
(SHORT) rc.xLeft, /*posn of window “*/ 
(SHORT) rc.yBottom, /*same as parent f 
(SHORT) (rc.xRight - rc.xLeft), 

(SHORT) (rc.yTop - rc.yBottom), 

hWnd, /*“parent window Fi 
HWND TOP, /*on top of parent */ 
ie /*frame 1D a 
NULL, /* unused mf 
NULL) ; /*“reserved a 


AAAI IIT. 
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break; 
end /*®switch*/ 


default: 
return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
break; 

end /*switch*/ 


return((MPARAM)OL) ; 
end 


ale JL A 0 0 I A 0 I 2 I I I I 
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sh 
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/* draws a 100 x 100 box from pt in color using 
/* the drawing mode specified 


ale J Se oe Ee Ie I I I I I I I I I I 
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void draw box(HPS hPS, PPOINTL pt, int mode, int color) 
begin 
POINTL ptcorner ; 


GpiMove(hPS, pt); /*move to current point */ 
ptcorner.x = pt->x + 100; /*set box size 100 x 100*/ 
ptcorner.y = pt->y + 100; 
GpiSetColor(hPS, color); /*fi11 box in red 
GpiBox(hPS, mode, &ptcorner, 

BL: OL) /*draw in new box 


Sh 
ey 
~Y 


5. 
“y 


SSS 


end 


pees 
MRESULT FAR PASCAL RectWndProc(HWND hWnd, USHORT msg, 
MPARAM mp1, MPARAM mp2) ‘ 


IL te Je J Ie ee I I I et I I 
aS VINA IN IN GRIN INNING INN BN IN INNIS i a a a ale 


/* This window is physically identical with the parent “*/ 
/* window. It receives mouse motion messages and moves a “y 
/* box around on the screen. When the left mouse button “*/ 
i is pressed, a red box is drawn at the current box ae 
/* location and the window closes, sending a NO PAINT ae i 
/* message to its parent so that the screen will not be “*/ 
/* erased in the main window. a 


begin 
static HPS hPS; /*handle to presentation space “*/ 
RECTL Fe; /* rectangle definition structure*/ 
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am Static POINTL pt, ptcorner; /* point structures my 
— static BOOL drawn; /*tells if one drawn yet x / 
©) HwNp hParent ; /*“handle to parent window J 
o 
switch (msg) /“jinterpret messages * / 
Begin 
am 
acase WM CREATE: 
| hPS = WinGetPS(hWnd) ; /*get cached PS * 
©) GpiSetColor(hPS, CLR_WHITE); /*and drawing color*/ 
om GpiSetMix(hPS, FM_XOR); /*drawing mode=XOR */ 
WinSetPointerPos(hPS, 100,100); /*pointer = 100,100%*/ 
©) WinShowPointer(HWND DESKTOP,FALSE); /*hide pointer oy 
@) WinSetCapture(HWND DESKTOP, hWnd); /*capture all * / 
/* mouse movements*/ 
© drawn = FALSE ; /*no rect drawn yet*/ 
a break; 
@. as WM BUTTONIDOWN: 
OM) pt.x = SHORTIFROMMP (mp1) ; /* x and y coords */ 
a BL.y = SHORT2FROMMP (mp1) ; /*are packed in mp 1*/ 
draw box(hPS, &pt, DRO FILL, CLR RED); 
o WinDestroyWindow(hWnd) ; /*exit from window” / 
- break; 


) 


tase WM MOUSEMOVE: 


> if (drawn) then 
begin 

2) draw box(hPS, &pt, DRO OUTLINE, 
eS CLR WHITE); /*XOR out old box */ 
a end 

" pt.x = SHORTIFROMMP (mp1) ; /* x and y coords “*/ 
©) pt.y = SHORT2FROMMP (mp1) ; /*“are packed in mp1*/ 
a draw _box(hPS, &pt, DRO_OUTLINE, 
| CLR WHITE); /*draw new box at 
©) drawn = TRUE; /*erase all future boxes*/ 
a break; 
Qase WM DESTROY: 
) WinShowPointer(HWND DESKTOP,TRUE ); /*show pointer i 

WinSetCapture(HWND DESKTOP, NULL); /*release mouse ow, 


Lit. 
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WinReleasePS(hPS) ; /*release PS aa 
hParent = /*get handle to parent window”/ 
WinQueryWindow(hWnd, QW PARENT, FALSE); 
WinSendMsg(hParent, NO PAINT, 
OL, OL); /*tell it net to repaint*/ 
break; 


case WM PAINT: 
WinValidateRect(hWnd, NULL, 


TRUE ) ; /*remove paint messages*/ 
break; 
default: 
return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
break; 


end /*“switch*/ 


return((MPARAM)OL) ; 
end 


The screen display of the overlapping boxes is shown in Figure 12-1. 


SUBCLASSING WINDOW PROCEDURES 


Another way of accomplishing the same thing as we did with the identical 
child window is to subclass a window procedure. Any time you have a 
window procedure that is almost the one you need, but needs to interpret a 
few messages differently, it is possible to create a new window procedure\/ 
that is called before the standard window procedure to intercept these mes-(_) 
sages. Instead of processing the remaining messages’ with 
WinDefWindowProc you instead call the parent window procedure directly 
to process them. WY 
The advantages of creating a superimposed identical window are that_) 
you can write a completely self-contained window procedure with local static 
and automatic variables, and its own Presentation Space. From the point of 
view of controlling the pointer visibility and position, this is somewhat 
simpler. Further, a subclassed window procedure never receives a _) 
WM_CREATE message and has no way to initialize variables before 
receiving other messages. 
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\_’ Figure 12-1. The boxes generated by the mouse-child box program.. Since the 
boxes are drawn in exclusive OR mode, they erase each other where 
they overlap. 


»@@ 


The advantages of subclassing a window procedure are that the sub- 
@™)classing routine is somewhat simpler, since it only needs to process a few 
messages, but the disadvantage may occur if it is necessary to draw into the 
presentation space from the subclassed window. The subclassed procedure 
can only know the handle of the main window’s PS if it is a global variable 
™) that it has access to, or if it is stored in the window words of that window. 
In this final example, we will rewrite the main window procedure 
MouseWndProc and make the subclassed procedure a portion of the 
©)RectWndProc procedure. Our main window procedure now must have a 
cached presentation space that remains in existence throughout the 
@ Window's life so that it can be available to the subclassed procedure as a 
global variable. We thus intercept the WM_CREATE message and create 
the PS, and set the drawing color and mix mode. When we receive the 
)command MRECT, we set the pointer position, make the pointer invisible, 
aset the global flag drawn, set the mouse capture, and subclass the window. 
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/ Sect gy co apa a ec a al oe eee et ge % / 
/* main window procedure which subclasses when the a 
/* MRECT command is received */ 
[Renew nw nn nn nnn no nn nn en nn on ee ee + *Y 
MRESULT FAR PASCAL MouseWndProc(HWND hWnd, USHORT msg, 
MPARAM mp1, MPARAM mp2) 
begin 
RECTL. rey /* rectangle definition structure * 
switch (msg) /*interpret messages x / 
begin 
case WM CREATE: 
hPS = WinGetPS(hWnd) ; /*get cached PS a 
GpiSetColor(hPS, CLR WHITE); /*and drawing color my 
GpiSetMix(hPS, FM XOR); /*set drawing mode to XOR*/ 
break; 
case WM PAINT: 
WinQueryWindowRect(hWnd, &rc); /*get current ar 
/* window dimensions  “*/ 


WinFillRect(hPS, &rc, CLR BLACK); /*fill with black */ 
WinValidateRect(hWnd, &rc, TRUE); /*remove paint msgs*/ 


break; 


case WM COMMAND: 
switch(LOUSHORT (mp1) ) 
begin 
case MRECT: 
WinShowPointer(HWND DESKTOP, 
FALSE); /*hide pointer 


a 
a / 


WinSetPointerPos(hPS, 100,100); /*set ptr=100,100%*/ 


WinSetCapture(HWND DESKTOP, hWnd);/*capture all 


al. 
aN f 


/*mouse movements*/ 
drawn = FALSE; /*no rect drawn yet*/ 


WinSubclassWindow(hWnd, 


RectWndProc); /*and subclass the window*/ 


break; 
end /*switch 


default: 


he 
Pas / 


C 
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return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
break; 
Pend /*switch*/ 


}Ooeeed@ 


return((MPARAM)OL) ; 
end 


d}@@ 


The subclassed window procedure, on the other hand, becomes simpler. 
Ont only needs to receive the WM—MOUSEMOVE §$and_ the 
) WM_BUTTONIDOWN messages. When it receives the mouse move mes- 
a) sages, it XORs out the old box position and draws a new one. When it 
receives a button down message, it draws the final filled box, reshows the 
pointer, unlocks the mouse capture, and reclasses the window so only the 
©) main window receives messages. Note that the default message case now 
@) only calls the main window procedure directly. 


/* This window is a subclass of MouseWnd Proc. It “/ 
/* receives mouse motion messages and moves a box around */ 
™) /* on the screen. When the left mouse button is pressed, */ 


ORD oy a red box is drawn at the current box location and / 

/* the subclass is removed, so that the main window ry 
O) 7/* again receives all messages. ‘| 
a /*sseesassasaaeaasSaS5S55555555555S55SSS5SSS5S5555=======" / 


~MRESULT FAR PASCAL RectWndProc(HWND hWnd, USHORT msg, 
MPARAM mp1, MPARAM mp2) 


Mm) begin 
RECTL rc; /* rectangle structure “/ 
oO Static POINTL pt, ptcorner; /* point structures xy 
on 
switch (msg) /“interpret messages “*/ 
begin 


case WM BUTTONIDOWN: 


pt.x = SHORTIFROMMP (mp1); /* x and y coords */ 
pt.y = SHORT2FROMMP (mp1); /* are packed in mp1*/ 
draw box(hPS, &pt, DRO FILL, CLR RED); 

WinShowPointer(HWND DESKTOP,TRUE ); /*show pointer = */ 


WinSetCapture(HWND DESKTOP, NULL); /*release mouse */ 
WinSubclassWindow(hWnd, MouseWndProc); /*restore main */ 
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/* window for all mesgs*/ 
break; 


case WM MOUSEMOVE: 
if (drawn) then 
begin 
draw box(hPS, &pt, DRO OUTLINE, 
CLR WHITE); /*XOR out old box*/ 
end 
pt.x = SHORTIFROMMP (mp1); /*x and y coords are a 


/* packed in mp1 os 


pt.y = SHORT2FROMMP (mp1); 
draw box(hPS, &pt, DRO OUTLINE, 


CLR WHITE); /*“draw new box af 
drawn = TRUE; /*“erase all future boxes*/ 
break; 

default: 


MouseWndProc( hWnd, msg, mp1, mp2); | /*call main window*/ 
/* forall others */ 
break; 
end /*switch*/ 


return((MPARAM)OL) ; 
end 


SCREEN VERSUS WINDOW COORDINATES 
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Since the mouse is always moving across the entire screen, even though the) 
screen may contain a number of windows, the coordinates that the mouse, 
messages return are always screen coordinates, having (0,0) at the lower left 
corner of the physical screen and the maxima at the upper right. By con-\/” 
trast, calls such as WinQueryWindowRect return values in window coordi-_) 
nates, where (0,0) is at the lower left corner of the current window. 

This distinction is likely to be important if you want to set the mouse 
pointer to a particular position relative to the current window. The calls YO 
hp2.WinSetPointerPos 11.WinSetPointerPos and WinQueryPointerPos refer\__ 
to the pointer position in screen coordinates, but you may wish to set the 
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pointer to some position relative to your current window. You can, however, 
make this conversion by using the WinMapWindowPoints call 


WinMapWindowPoints(hFrom, hTo, &points, count); 


where 

hFrom is the handle to the window from which the conversion is to be 
made. If the conversion is from screen coordinates, this should 
be HWND_DESKTOP. 

hTo is the handle to the window to which the conversion is to be 


made. If the conversion is to screen coordinates, this should be 
HWND_DESKTOP. 


& points is a pointer to an array of points defined as POINTL struc- 
tures, or, in other words, long x and y values. 


count is the number of x,y point pairs to convert. 
Thus, to set the pointer in the middle of a window, you would write 


RECTL rc; /*window rectangle*/ 
POINTL point; /*one point structure”/ 


WinQueryWindowRect(hWnd, &rc); /*get the window size */ 
point.x = rc.xRight / 2; /“half of x width or 
point.y = re.yTop /2: /“half of y height ey 


WinMapWindowPoints(hWnd, HWND DESKTOP, &point, 1); 
WinSetPointerPos(HWND DESKTOP, point.x, point.y); 


CHANGING THE POINTER SHAPE 


Normally the mouse pointer is an arrow sloping diagonally upward, with its 
“hot spot” one pixel above and to the left of the point. It changes to a 
double-headed arrow when you move it across the boundary of a window 
with a sizable frame. There are a number of pointer icons you can obtain 
from the system and use as you wish, and the handle to these icons can be 
obtained by the WinQuerySysPointer call 
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HPOINTER hPtr; 


hPtr = 
WinQuerySysPointer(HWND DESKTOP, SPTR HANDICON, TRUE) ; 


where the icons you can obtain are 
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SPTR_ARROW the arrow pointer 

SPTR_TEXT the text I-beam pointer 

SPTR_WAIT the hour glass 

SPTR_SIZE the size pointer 

SPTR_MOVE the move pointer 

SPTR_SIZENWSE the downward-sloping, double-headed arrow 
pointer 

SPTR_SIZENESW the upward-sloping, double-headed arrow pointer 

SPTR_SIZEWE the horizontal double-headed arrow pointer 

SPTR_SIZENS the vertical double-headed arrow pointer 

SPTR_APPICON the standard application icon pointer 


SPTR_QUESICON the question mark icon 
SPTR_BANGICON the exclamation mark 
SPTR_NOTEICON the note icon 


SOSCOOeeee 


Once you have obtained the handle to the desired icon, you must set that 
pointer and show it using the calls 


Oc 


WinSetPointer(HWND DESKTOP, hPtr); /"select pointer */ 
WinShowPointer(HWND DESKTOP, TRUE); /*show the pointer*™/ \/ 


Because the system will change the pointer every time it leaves the current 
window, you must make these two calls every time you get aw 
WM_MOUSEMOVE message, since the mouse may have just moved in 
from outside the window. 


< 
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13 Building a Dynamic Link 
Library 
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OYOS/2 provides you with the unique ability to write library routines that can 
a) be loaded with your program at run time. This allows several programs to 
use the same routines and allows you to change the internal workings of such 
library routines without having to recompile and relink the programs that 
use them. In fact, you can view these dynamic link library modules (DLLs) 
yas user-definable extensions to the operating system. 

a It is possible to write a series of functions in a module and compile them 
as usual and link them as ordinary parts of your program, and then later 
decide that these routines can be a DLL and, with virtually no changes, 

recompile and relink the same routines to be used in this new form. 

> The OS/2 program loader is signalled that a DLL is needed when the 
program is linked with a special small library file that indicates that all of 
the modules to be called are located in this DLL. Then OS/2 looks in the 

subdirectories specified in the LIBPATH statement in CONFIG.SYS to 

@ find these DLLs. The LIBPATH will always contain C:\OS2\DLL and 
may contain a number of other directories. In order to tell OS/2 to look in 

the current directory as well, you should include the “.;” statement in the 

search list. Once you have finished debugging your DLL, it is common to 

put it in a directory with other application-program level DLLs, such as 
C:\MYDLLS. Then you can be sure it will be accessed no matter which 
directory you are running from. 


LIBPATH=. :C=s\OS2Z\DLLsCs\MYDLLS:€: \0S2: re 
1 
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CREATING A SIMPLE DLL 


SOeeeode 


There are a number of simple rules you must follow to create a DLL. The 
most important is that all of the function calls ina DLL will be far calls and 
all of the variables passed to the function will be referenced as far addresses. ¢ ) 
Since we have habitually linked with the large model library this will not. 
present us any new challenges. In addition, you must compile your DLL C Y 
code using the /DDLL switch that defines DLL as a symbol. This forces WY 
some of the include files to provide different function prototypes. 

In addition, you must compile the DLL functions so that DS is not equal | 
to SS, which means that you use the switches /Alfu. Rather than linking 
with LLIBCE.LIB or LLIBCMT.LIB, the most common option is to link W 
with LLIBCDLL.LIB, which provides all of the standard C- library func- VW 
tions in reentrant form. This will not work, however, if you will have more | 
than one thread running in your DLL, although you can have several 
threads running in the calling program. For this case, you must create the \/ 
CRTLIB libraries as discussed below. 

Finally, the LLIBCDLL.LIB library uses the alternate floating point , 
math library functions rather than the math coprocessor, and for these you 
must also use the CRTLIB functions. 


THE PDLL LIBRARY 


In this example, we jill write a small C function that applies the quadratic 
formula to three supplied coefficients and returns the two real roots, or an 
error flag if the result is complex. We see that the function and the sur- 
rounding code are no different than if we had created a module to link 
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directly with a main program. 


/* PDLL Library - with the quadratic formula evaluator “*/ 
#include <cdefs.h> 

#include <math.h> 

#include <stdio.h> 

#define INCL BASE 

#include <os2.h> 

[Bnei ea ee HS SSR Rr een tenner eee eee ss 
BOOL FAR PASCAL quadform(double “x1, double *x2, double a, 
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double b, double c) 
/* calculates the two roots of a 2nd order polynomial ae 
\_/ begin 


ABAALL , 


double rad; 
BOOL valid; 


9 


()/* calculate value under square root 


arad = b* b- 4.0% a” ce: 


O) if (rad < 0) then 
™ valid = FALSE; /*can't take square root of neg number*/ 


else 
begin 
M™, valid = TRUE; /* OK if >= 0 ar 
~ *%| = (=b + sert(rad)) / (2.0 * a); /*ealculate rooti*/ 
f Wyo = (oh =egrtlrad)) / (2.0 * a); #*calewlate root?*/ 
O end 
a return(valid); /*return flag for validity of answer*/ 
~end 
To compile this library module, we use the C command 
a cl /Zei /c /G2sc /W2 /Alfu /DDLL pdll.c 


@_ Then, to link the program to make a DLL, we use the following defi- 
nitions file: 


em LIBRARY PDLL INITINSTANCE 
PROTMODE 

) DESCRIPTION ‘Quadratic DLL’ 

vm DATA MULTIPLE NONSHARED 

~— HEAPSIZE 1024 

©) Exports 

) QUADFORM @1 


© where we note the EXPORTS statement describes the name of the functions 

mm we are going to be able to access when the DLL is loaded. The 
-INITINSTANCE statement describes the fact that each instance of the 

\_’ DLL requires some initialization code. This is required for all DLLs linked 

©) with LLIBCDLL.LIB. 

Finally, we link the DLL using the following response file 


Ait. 
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pdll.obj /CO /A:16 
pdll.d1l1 /NOI 

pdll.map 
llibcd11.1ibtos2.1lib /NOD 
pdll.def 


WRITING A PROGRAM TO CALL THE DLL 


CASE TTT TTS 


Now we need to write a program to call the QUADFORM function in the__ 
DLL. We will need to generate a function prototype for each function in the 
DLL, which in this case is just the QUADFORM function. The 


WY 
pdll.h 
WY 
file contains the simple statement & 
BOOL FAR PASCAL quadform(double *x1, double “x2, double a, WwW 
double b, double c); | 
a, 
The program to call this function can be as simple as the following: & 
#include ‘'pdll.h' ‘oe 
#include <stdio.h> 
#include <cdefs.h> Y 
| me, 
/* simple example program to call the quadratic “| a 
/* caleulator fn a BLL 7 ed 
void cdecl main() VJ 
begin ) 
double a, B, Gs x1,.%2Z5 Y 
int valid; WwW 
" 7 
a= 1.0; /“initialize coefficients “/ 
b = 2.0; Y 
c = 1.0; , 
valid = | 
quadform(&x1, &x2, a, b, c);  /*call the DLL function*/ 
if (valid) /*print out the answer*/ > 
printf("xl = %f, x2= %f\n', x1, x2); 
else 
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printf('‘complex roots: valid=%d\n'', valid); 


0) 
= 
2% 
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Compilation of this program proceeds as usual, with no indication that 
quadform won’t be linked with the program directly: 


cl /Zpei /c /G2sc /W2 /Alfu cquad.c 


However, when you link the program, you include an IMPORTS statement 
in the .DEF file that gives the name of the DLL and the name of any refer- 
enced functions: 


oO 
_/NAME CQUAD 
O DESCRIPTION 'DLL Test Program’ 
STUB 'OS2STUB.EXE' 
CODE MOVEABLE 
DATA MOVEABLE MULTIPLE 


HEAPSIZE 1024 
‘ YSTACKSIZE 4096 


> 


IMPORTS 
PDLL.QUADFORM 


»o@ 


The link response file is no different than if no DLLs were referenced: 


) 


cquad.obj /CO /A:16 /NOD 

cquad.exe /NO| 
M\cquad.map 

llibce. libtos2.]lib /NOD 

cquad.def 


J 


Note that it is not necessary to link the main program with any special 


) 


library. 


dO 


LOADING A DLL AS NEEDED 


emOne problem with linking all DLL calls using the IMPORTS statement is 
that the program will not run if even one of the referenced DLLs can not be 
found. This can lead to a portability problem, where some users may have 
yall the DLLs in place and other may not. 
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Instead, you can load the DLLs as needed and issue error messages at | 
run time if the DLLs can’t be found. There are just two routines you need to 
use for this purpose: 


err = DosLoadModule(ob jbuf, objlen, 
modulename, &hMod); /*load a DLL*/ 


/*get address of function*/ 
err = DosGetProcAddr(hMod, procname, &procaddr); 


OCCOCOOOOEOOOOOEEEOCOOE 


where 

err is zero if there are no errors. 

objbuf contains the module name where the error occurred. 

objlen is the length of the objbuf buffer. 

modulename is the name of the DLL module (no path, no extension). 

hMod is the module handle returned by the first call and used, 
by the second. 

procname is the name of the procedure within the DLL. 

procaddr is the far pointer to the procedure you want to call. 


The following code illustrates exactly how to load and call a function in a{_) 
DLL: 


/* simple example program to load and call the quadratic */ 
/* calculator in a DLL *Y 
#define MAXLEN 80 

#define INCL BASE 

#include <os2.h> 

#include <stdio.h> 

#Hinclude <cdefs.h> 


void cdecl main() 

begin 
double a, b, c, xl, x2; 
int valid, err; 
HMODULE hMod; 
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char ob jbuf[MAXLEN] ; 
BOOL (far pascal “quadform)(); /*pointer to address*/ 


d@0edd0009 


a= 1.0; /*initialize coefficients */ 
b = 2.0; 
c = 1.05 
Merr = DosLoadModule(objbuf, MAXLEN, ''PDLL'', &hMod); 
err = DosGetProcAddr(hMod, ''QUADFORM'', &quadform); 
if (err == 0) then /*call the DLL function*/ 
@ valid =(*quadform)(&x1, &x2, a, b, c); 
ay if (valid) 


printf(''x1 = %f, x2= %f\n'', x1, x2); /*print answer */ 
else 
Om printf(''complex roots: valid=%d\n'', valid); 
end 


m 


om 
BUILDING THE C RUN-TIME DLL 


ODVIf you wish to create a DLL that can work in a multithread environment and 
a that will use the math coprocessor, you must build the special C run-time 
DLL CRTLIB.DLL. This will be loaded along with your DLL to provide 
reentrant versions of the C functions. Both IBM C/2 1.1 and Microsoft C 
Osu provide a batch CMD file that will link together a number of C run-time 
routines into a DLL. You must build this DLL and the accompanying C 


aplibrary 


a’ CRTILIB.DLL 
CRILIB<L IB 
~~ 
aesing the command file CDLLOBJS.CMD. You will then link your DLL 


with CRTDLL.OBJ followed by your own file to give your DLL the usual C 
startup code. 


) 
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Linking a Program with CRTLIB.DLL 


Linking amounts to specifying CRTDLL.OBJ as the first module, followed \/ 
by your own module(s). You must specify the linker switches /NOI so that LV 
case is not ignored in the generated symbols and /NOD so that no default 


libraries are linked: = 
link @ filec.1 | 
Ww 
where the response file contains 
WH 
crtdll.objtfilec.obj VU 
filec.d11 /NO! /CO wY 
filec.map /M ‘? 
crtlib. Jib + 052.116 /NOD | 
filec.def Y 
WY 


If the library routines use the Presentation Manager, you can then run the 
Resource Compiler to include any resources: 


re filec.rc filec.dttl 


The Definitions File 


0006004 


The .DEF file for a DLL must contain the LIBRARY statement, which¢ ) 
defines the linked file as a DLL. Each function that you wish to call must be 
specified in the EXPORTS statement. Here you must be careful about the 
calling convention you use. If your functions are called using the Pascal\v 
calling convention, their names must be all uppercase. If your functions are(_ } 
called using the C calling convention, then they must match the case of the 
routines in the C module and must be prefixed by an underscore (_). 


} 


¢ 


LIBRARY FILEC 
PROTMODE 

DESCRIPTION ''Any text’ 
DATA MULTIPLE NONSHARED 


EXPORTS 
_GetFile 
FILEDIALOG 
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©) USING IMPLIB TO MAKE THE LIB FILE 


Now that you have created your DLL, you must tell programs that they are 
'_/ to use it when they load. If you have quite a number of entry points it is 
™) easier to make an import library using IMPLIB than to specify all of them 
@) in the program’s .DEF file. You do this by making a small LIB file that you 
ok with each program that contains the information on the needed DLL. 
~_ This LIB file is produced by the IMPLIB program 


~ 
IMPLIB filec. lib fi lec.def 
o-~ 
Then you simply link the resultin 
a x ply g 
mm t i lec é | | b 


™» with each program that will use the FILEC.DLL. All of the routines that 
were EXPORTed in the DLLs .DEF file will now be defined in the filec.lib 
~~ file and will be linked automatically. 


am», 


om, 
pe DEBUGGING A DLL 


™) It 1s possible to use CodeView to debug a DLL if you compile it using the 

oa / Zi switch as we did here and link it using the /CO switch. Then, when you 
start up the program to be debugged, you must have the DLL in the current 
‘subdirectory. Then you start CodeView with the command 


a 
cvp -| Tilec preg 
oo, 
This tells CodeView that it will be debugging 
om Prog Cc 
@) and 
M™filec.dll. 
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14 Printing Graphics and Text 
under OS/2 
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OS /2 is designed so that all requests to print are passed to the first part of a 
amdevice driver that places them into a spool file. Then a spooler queue 
manager program (SPOOL.EXE) writes the file to disk and makes it a print 
“job. When the printer or plotter is ready to print, the spooler queue processor 
program (PMPRINT.QPR) reads the file from the print queue and passes it 
to the second part of the device driver. The advantage of this process is that 
a number of requests to the same printer or printers can be queued by sepa- 
rate tasks and printed in sequence, but that all of them remain device inde- 
pendent. 
™ The spooler queue manager is in fact the Print Manager program that 
_~Starts automatically with OS/2 and displays a printer icon in the corner of 
"the screen. You can click on the spooler icon and examine the contents of the 
Orgueue for each device and remove or duplicate jobs in the queue. You actu- 
ally select which devices are connected to which queues using the Spooler 
Program. If you click on Setup in the Print Manager’s menu, you will be 
able to select the printers currently installed and the queues to which they 
are attached. 
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PRINTERS, PORTS, AND QUEUES 


Every printer on your system can have a Printer Name associated with inv 
Such printers can be local or can, in fact, be on a local area network. Fac) 
named printer must be associated with a printer hardware port, such a 
LPT1, LPT2, COM1, or COM2, etc. You must always associate eac 
printer with a specific named queue. In addition, you must select a Devide 
Driver program for each printer to be used. Often, it is convenient to simpl_> 
use the Print Manager to select the current default printer and use th 
default name and queue. a 
When OS/2 PM is installed, the default printer is named PRINTERI, 
is associated with the printer queue LPT1Q, it is connected to port LPT\_) 
and the default device driver IBM4201 is selected. You can add devig 
drivers and change printer connections using the Print Manager program 
You can also create new queues with new names, but there can only be on 
default queue. Most standard PM programs work on the current defau.__ 
queue and if you wish to have your program work on several possible queue 
you will have to install a menu with a list box to select the queue you wish t¢ 
use. In the examples below we will operate on the default queue and assume” 
that the user invokes the Control Panel program to change between queues\_/ 


WO 


THE OS2.INI PROFILE VU 
wo 


Most of the parameters that are referred to as default parameters ap 
included in the OS2.INI file in the c:\OS2 directory. This file contains thé 
default screen colors, the default border width, the default printer namés” 
the default queues, and the default fonts. You can examine the values in th__ 
file using the WinQueryProfileString function, which has the form 


WwW 

WinQueryProfileString(hAB, appname, keyname, default, YY 
profile, maxstring); 

VW 
where | 

wy 
hAB is the handle to the anchor block Y 
appname is the name of the application program that requir 


initialization data. 
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aovkeyname is the name of the feature within the program for which 
~ we want information. 

oaefault is the string that is returned in profile if the keyname 
pa can’t be found. 

abrofile is the text string returned from the query. 

omaxstring is the maximum length of the profile string. 

on 


cPRINTING A SCREEN 


since PM printing or plotting is device independent, you should be able to 
Orke any screen of information and print or plot it. Printing or plotting the 
ontents of a graphical screen can be quite simple if you are sure what 
device you are going to print on. In such a case, you simply initialize the 
contents of a DEVOPENSTRUC structure accordingly: 


DEVOPENSTRUC dop 


= {(PSZ)''LPT1Q"', /*queue name mf 

™M  (PSZ)''1BM4201"', /*device driver name ay 
pe OL. /*driver data args af 
(PSZ)''PM Q STD", /*data format = 

Oo (PSZ)''comment'', /*“optional comment a 
S OL, /*queue processor name xf 
OL, /“optional queue processor parms*/ 

Oo OL, /“optional spooler parameters “*/ 
a, OL}; /*optional network parameters “*/ 


ny the common case, however, you check the current status of the OS2.INI 

ile and decompose the configuration string returned by the query profile 
“string call. This first call looks for the “PM_—SPOOOLER’” text and returns 
ae name of the default printer: 


) 


ainQueryProfileString(hAB, 'PM SPOOLER', ''PRINTER', |", 
szTemp, MAXLEN); 


»®@ 


,“remove trailing semicolon*/ 
zTemp[strlen(szTemp)-1] = 0; 


) 
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Then, we look for the string identified with th 
PM_SPOOLER_PRINTER text within the PM_SPOOLER application: 


WinQueryProfileString(hAB, ''PM SPOOLER PRINTER'',szTemp, |", 
szSpIrPrntr, 256); 


In the default case, this will return the string 
“LPT 13 |BMAZO 13 LPT 1033" 
where 
LPT1 is the name of the current port. 
IBM4201 _ is the name of the current device driver. 


LPT1Q is the name of the current queue. 


SOSOOCOOOCCSOOO EL 


This can be somewhat more complex, however. If the current device driver is 
one of the plotters in the PLOTTERS.DRY file, then the entry point for 
that device is also specified. In addition, if there is more than one queue, alhw 
of the queue names are returned separated by commas, with the default 
queue first: 


WY 

'LPT1;PLOTTERS. 1BM6180;LPT1Q,PLOT1Q; ;" &) 

In any case, we can clearly parse that string and put its substrings into the) 

DEVOPENSTRUCT structure. Y 

WinQueryProfileString(hAB, ''PM SPOOLER'', ‘PRINTER’, |, ‘e 

szTemp, 80); 

/*remove trailing semicolon a 7 

szTemp[strlen(szTemp)-1] = 0; YD 
WinQueryProfileString(hAB, ''PM SPOOLER PRINTER',szTemp, '', 

szSpIrPrntr, 256); Y 

strcpy(szPlot, szSpIrPrntr); /*get another copy */) 
pchScan = strchr(szSpIrPrntr, |; ); /*“look for ; a 

pchScant+; /*go just beyond itty 

pchScan = strchr(pchScan, ';°); /*look for 2nd; *“/\W) 
pchScant++; /*go beyond it = 


©SOeeode 


LL 


a 
oO 
fr 
o~ 
pds 


“set next 
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al. 
aS / 


*(pchScan + strcspn(pchScan, rea =e 


a> 


jop.pszLogAddress = pchScan; /*logical queue name*/ 
cf 

chScan = strchr(szSpIrPrntr, ';°); 

pchScant+; 
@& (pchScan + strcspn(pchScan, ''.,;'')) = 0; 


adop . 


pszDriverName = pchScan; 


/*“copy in driver name*/ 
/*“default queue proc */ 


dop.pszQueueProcName= NULL; 
Oop .pszQueueProcParams=NULL ; /*no queue proc parms*/ 
aadop.pszSpoolerParams=NULL ; /*default spooler parms*/ 
dop.pszNetworkParams=NULL ; /“def network parms */ 
Jop.pszDataType = ''PM Q STD''; /*std queue data type”*/ 
@vop.pszComment = "comment"; /*any comment or NULL*/ 
o 


ovhe DRIVDATA Structure 


Orne third argument in the DEVOPENSTRUC structure is the address of 
Oy nother structure of variable length called the DRIVDATA structure. Since 
o™he length and content of this structure vary with the device, its first entry is 
othe structure length in bytes, followed by the version number of the device 
driver that it requires. The important field in this structure is the entry point 
Ona multiple device driver file such as PLOTTERS.DRV, which contains 
rivers for a number of similar Hewlett-Packard and IBM plotters. If the 
eadlevice driver has only one entry point, then this string must be NULL. 


/*“length of this structure ae 


a@grivdata.cb = 44L; 
/*version of driver required “*/ 


drivdata.1IVersion = OL; 


~ dop.pdriv = &drivdata; /*ptr to drive data structure “/ 
o 
* look for device name in device driver field*/ 
pchScan = strchr(szPlot, ';°); 
(chScant+; 
Oo | 
| = strcespn(pchScan, '..); /“look for entry point name “*/ 
Mr (i< strlen(pchScan)) then 
begin 
pchScan += ij + 1; 


*(pchScan + strespn(pchScan, '|'.,;'')) = 0; 
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/* get name of entry point i 
strcpy(drivdata.szDeviceName, pchScan); 
end 
else 
strcpy(drivdata.szDeviceName, |"); (Poe aul) Y 


THE PS, THE WINDOW, AND THE DEVICE 
CONTEXT 


6000008000 


Thus far we have dealt with windows and with presentation spaces. When; 
we consider devices besides the screen, we will also need to utilize device 
contexts. A window is a screen area that is maintained and refreshed by a 
particular routine, called a window procedure. A presentation space contains\_» 
a table of values describing how the window is to be drawn, including font, 
character, line and marker colors, and line type. A device context is a 
device-specific table of values describing how a particular device is to bb“ 
used for drawing. To confuse matters somewhat, a screen PS, such as those\y 
we have dealt with so far, contains some device-specific information, but this 

is not the case for printers and plotters, which require that you associate a, 
device context with a presentation space before you begin drawing. 


a, 

The Plotter Device Context Y 
Ww 

Now that we have loaded the DEVOPENSTRUCT, we can open a printer) 
device context using the DevOpenDC call © 
DevOpenDC(hAB, type, token, count, &devopen, comp); ) 
where WY 
hAB is the anchor block handle for this thread. is 
type is the type of device context, which may bew 
OD_QUEUED, OD_DIRECT, OD_INFO;_> 
OD_METAFILE, or OD_MEMORY LY 

token is a token to search for in OS2.INI. This is overridden be 


the DEVOPENSTRUC parameter. If the token is “‘*” 
no information is read from OS2.INI. 
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™) count is the number of long entries in the DEVOPENSTRUC 
oa structure to read. 

a, & devopen is the address of a DEVOPENSTRUCT structure. 

©) comp is a handle to a device context compatible with the bit 
am map to be used in this device context. Used only with the 


type OD_MEMORY. 
om 


~~ To open the device context for a plotter, we simply call 


a hDC = DevOpenDC(hAB, OD QUEUED, ''*"', 5L, 


(PDEVOPENDATA)&dop, NULL); 
on 


i the Plotter Presentation Space 


©) The plotter device context must finally be associated with a plotter presenta- 

tion space, so that we can call the same drawing routines using this new 
hPS. We do this using the GpiCreatePS call, where we require a normal 
presentation space. We would also like this presentation space to draw full 

) scale on whatever plotter we attach, regardless of its resolution and regard- 

oy less of the size of the window on the screen. If we scale our drawing to the 
current window size, we can query that size and set these values into the 
SIZEL structure before creating the PS. 


WinQueryWindowRect(hWnd, &rc); /*“get current window size */ 
siz.ex = re. xRignt; /*plot full size on device*/ 
@mysiz.cy = rc.ylop; 
ees NPSPrinter = GpiCreatePS(hAB, hDC, &siz, 
: PU ARBITRARY | GPIA ASSOC | GPIT NORMAL); 


Note that the hDC is the one just created for the printer and that the 
©) GPIA_ASSOC bit must be set. 
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The DevEscape Printer Calls 


When you are printing to a specific plotter or printer, you may have to tell inv” 
things you wouldn’t need to tell a display, such as setting the printer mode t(_) 
draft or letter quality, and ejecting the page at the end. The DevEscape 

YO 
function has the form 


DevEscape(hDC, code, incount, &indata, outcount, ous: 
Ww 

where 
WY 
hDC is the handle to the device context. VU 
code is the code to be sent to the device driver. V/ 
incount is the number of bytes in the input data buffer. WY 
indata is the input data buffer. Y 
outcount is the number of bytes in the output data buffer. Y 
outdata is the output data buffer. & 


There are 11 escape codes defined in OS2 1.2, but the only ones we will usp » 


P 


are 
DEVESC_GETSCALINGFACTOR 
DEVESC_STARTDOC 
DEVESC_ENDDOC 
DEVESC_NEWFRAME 
DEVESC_DRAFTMODE 


THE COMPLETE PLOT ROUTINE 


void plot(HAB hAB, HPS hPS, HWND hWnd) 
begin 
CHAR szTemp[80], szSpIrPrntr[256], szPlot[256]; 
PCH pchScan; 
DRIVDATA drivdata; 
SIZEL siz; 
RECTL rc; 
HDC hDC; 
HPS: hPSPrinter; 
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long ocount, odata; 
DEVOPENSTRUC dop; 
ink err gt 


ALAS 


weWinQueryProfileString(hAB, ''PM_SPOOLER'', ''PRINTER', '"', 
| szTemp, 80); 
szTemp[strlen(szTemp)-1] = 0; /*remove trailing semicolon*/ 
waWinQueryProfileString(hAB, ''PM SPOOLER PRINTER’, szTemp, 
f bit — <= 
, szSpIrPrntr, 256); 


O\trcpy(szPlot, szSpIrPrntr); /*get another copy mf 
r» /*for device name parse “*/ 
pchScan = strchr(szSpIrPrntr, ';');  /*look for Ist; */ 
ochScant+; /*go just beyond it*/ 
MpchScan = strchr(pchScan, ';'); /*look for 2nd ; ar | 
gpchscant; /*go beyond it oF | 
(%* set next . , or ; to null sat 
ox (pchScan + strcespn(pchScan, ''.,;')) = 0; 
dop.pszLogAddress =  pchScan; /*logical queue name*/ 
geochScan = strchr(szSpIrPrntr, ‘;°); 
pchScant+; 
)(pchScan + strespn(pchScan, ''.,;'')) = 0; 
@mop.pszDriverName = pchScan; /*“copy in driver name oF 
dop.pszQueueProcName= NULL; /*“default queue processor */ 
ee ee eee ne /*no queue proc parms mi 
(op.pszSpoolerParams=NULL; /*default spooler parms “*/ 
afop.pszNetworkParams=NULL ; /*‘default network parms  */ 
“ gop.pszDataType = ''PM Q STD';  /*standard queue data type”/ 
Myop.pszComment = ''comment'’; /*any comment can go here */ 
drivdata.cb = 44L; /*length of this structure*/ 
Oyrivdata. Version = OL; /*version of driver reqd “*/ 
emop.pdriv = édrivdata; /*ptr to driver data struct*/ 
: look for device name in device driver field*/ 
a™mchScan = strchr(szPlot, ';'); | 
ggchscantt; 
Oy = strcspn(pchScan, ''.''); /*get entry point name “*/ 


aif (i < strlen(pchScan)) then 


o 
om 
o 
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begin 
pchScan += i + 1; 
*(pchScan + strcspn(pchScan, ''.,;')) = 0; 
strcpy(drivdata.szDeviceName, pchScan); 
end 
else 
strcpy(drivdata.szDeviceName, '"');  /*or null 


hDC = DevOpenDC(hAB, OD QUEUED, ''*'', 5L, 
(PDEVOPENDATA)&dop, NULL); 


WinQueryWindowRect (hWnd, &rc); /*get current window size 
/*“plot full size on device*/ 


Siz.¢x — re. RRight; 
Siz.cy = re.yTop; 
hPSPrinter = GpiCreatePS(hAB, (HDC)hDC, &siz, 


PU ARBITRARY | GPIA ASSOC | GPIT NORMAL); 


DevEscape(hDC, DEVESC GETSCALINGFACTOR, O, NULL, 
&o0count, &odata); 

DevEscape(hDC, DEVESC STARTDOC, 4L, ''Plot'’, 
&ocount, NULL); 


drawscreen(hPSPrinter); /*draw on this device 
DevEscape(hDC, DEVESC NEWFRAME, OL, NULL, 

0, NULL); /*page eject 
DevEscape(hDC, DEVESC ENDDOC, OL, NULL, 

0, NULL); /*close the document 
GpiAssociate(hPSPrinter, NULL); /*disassoc from display 
DevC loseDC(hDC) ; /*discard the DC 
GpiDestroyPS(hPSPrinter) ; /*and the PS 
end 


sh 
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15 Communicating Through 
serial Ports 
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Many devices that you might wish to connect to your computer can be con- 
ynected using the computer’s serial ports or COMM ports. These ports 
provide a standard method of communicating with devices using the RS-232 
standard for serial communication. Data are sent through RS-232 ports as 
8-bit bytes, but the the bytes are decomposed into a bit stream and sent seri- 
Myally and reassembled into 8-bit quantities at the other end. 


>, 
BAUD RATES 


a 
Since the data are sent a bit at a time, the data rate or baud rate is roughly 
equivalent to the number of bits per second. Each character or byte of data 
actually consists of | start bit, 8 data bits, and 1 or 2 stop bits, so the baud 
@»rate is about 11 times higher than the character transfer rate. Data rates 
Vary from 110 baud for historical reasons up to 9600 or 19,200 baud. PS/2 
computers alllow transfer at 19.2 kbaud but AT hardware only allows baud 
rates up to 9600 baud. Clearly, the higher the data rate the better, and most 


o™modern instruments allow transfer at 9600 baud. 
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PARITY 


All ASCII characters can be represented unambiguously in 7 bits (0-6), and 
bit 7 of the serially transmitted character is sometimes used as a parity bit) 
There are four cases for the parity bit: 


WY 
Null Bit 7 is always 0. Cy 
Odd Bit 7 is on if it makes the total number of bits on odd. L/S 
Even Bit 7 is on if it makes the total number of bits on even. UV 
Mark Bit 7 is always on. Y 
WY 
THE COM DEVICE DRIVER = 
A copy of the COM port device driver is loaded for each active COM port it__ 
your machine if you specify that this driver is to be loaded at OS/2 installa; 
tion time or if you have the statement | 
VW 
DEVICE=COMO1.SYS 
VW 
or | 
wy, 
DEVICE=COM0O2.SYS \) 


The COMO] driver is loaded for AT-class machines and the COM0O2 drive__ 
for PS/2 machines. These drivers provide interrupt-driven service of datg \ 
transmission through a series of simple calls to the DosDevIOCtrl function 

It is also possible to select the handshaking technique used. 


PIN ASSIGNMENTS OF RS-232 CONNECTORS 


6006 


The primary COM port on PS/2s is a 25-pin male connector. Additiong 
ports on plug-in cards and the ports on AT-class machines are 9-pin connec 
tors. The pin assignments are shown in Table 15-1. 
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Table 15-1. Pin Assignments on Serial Connectors 















o 
m 
face [eft | Da care Daa 


©) The primary purpose of serial communication was originally to connect a 









@ terminal to a modem, a modem to a phone line, and at the other end another 
modem to a computer. Serial ports are classified as DCE (Data Communi- 
cations Equipment), such as modems, and DTE (Data Terminal Equip- 

ment), such as computers. DCE connectors have pins 2 and 3 and pins 5 and 

20 reversed, so that a straight-through cable between DCE and DTE con- 

| nectors has RD connected to TD and Clear to Send connected to Data Ter- 

“minal Ready. More commonly, two computers or other devices with DCE 

@M connectors must be attached, and this requires a “crossed cable” or “null 

ymodem” cable which has pins connected as shown in Table 15-2. 
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Table 15-2. Pin Assignments in a Null Modem 


Signals 25-pin connections 


— 
I 
— 


ZAI 


NO 
I 
1S) 


TD-RD 


1S) 
! 
N 


RD - TD 
RTS - DCD 
DCD-RTS 


oe 


CTS & DSR - DTR 5 & 6 - 20 
DTR - CTS & DSR 20-5 & 6 


e€ 


GND -GND GND - GND 


aN 
' 
oo 


OPENING AND CONTROLLING A COM PORT 
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A COM port is opened using the DosOpen call, where many of the argu- 
ments have no meaning. The standard call has the form 


err = DosOpen(filename, &handle, Saction, size, attribut 
openflag, mode, reserved); 


filename The path and name of the file (or device) to be used. 
& handle The address where the file handle is to be returned. 
& action The action taken: 


0x0001 file exists 
0x0002 file created 
0x0003 file replaced 


size The file size in bytes. 


attribute The file attribute bits: 
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0x0001 read only file 
0x0002 hidden file 
0x0004 system file 
0x0010 subdirectory 
0x.0020 file archive 


Action taken if the file exists or does not exist: 
If the file exists 


xxxx0000 fail 
xxxx0001 open file 
xxxx0010 replace file 


If the file does not exist 


0000xxxx fail 
0001xxxx create file 


Contains the bits D, W, F, I, S, and A mapped to 16 bits as 
follows: 


15 144 13 12 11 109876543210 
CY F = = Se |] 6S 8 = AA 

D 0 means a file and | means device is a drive. 

I Inheritance flag. If O the file handle is inherited by a 
spawned process and if | the handle 1s private. 


W Write-through flag. If 0, the file writes may go through a 
system buffer cache and if | the file I/O is done to disk 
before the call returns. 


F If O errors are reported through the system critical error 
handler and if 1 they are reported to the caller through the 
return code. 


S Sharing mode field. Determines whether a file can be shared. 


001 deny read/write access 
010 deny write access 
011 deny read access 
100 allow read/write access 
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A access mode field 


000 read only 
001 write only 
010 read/write access 


reserved Must be zero. 
If the return code is O there is no error. If non-zero, some of the errors are 


0 no error 

2 file not found 

3 path not found 

4 too many files open 

5 access denied 

26 not an OS/2 or DOS disk 
32 sharing violation 

112 = disk full 


Opening a COM Port 


For opening a COM port, only a few arguments are used: 

err = DosOpen(''COM2'', &EhCom, Saction, OL, 0, 1, 0x12, OL); 
where 

"COM2" The port name as a zero-terminated ASCII string. 

&hCom The returned handle to the communications port. 


&action The action taken. This will always be 0001 = “‘file exists.” 


OL The file size is not used. 

0 The file attributes are not used. 

I The open flag defines action to take: open it if port exists and fail 
if it doesn’t. 


0x12 The open mode. The sharing mode is 001, meaning deny, 
read/write access to any other task, and the access mode is 010, 


meaning read/write access is requested. 


8000800 OOOO OOHOOOOOOOOOOOOO CE 
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OL Reserved field. 


) 


‘ err Return value. Should be 0 if the open is successful. 


“"y You then write to and read from the COM port using the DosRead and 
)DosWrite functions 


)dosRead(handle, buffer, buflen, &bytesread) ; 
@DosWrite(handle, buffer, buflen, &byteswritten); 


where 

handle is the file handle returned by DosOpen. 

butter is the address of an array to transfer bytes to or from. 
we buflen is the number of bytes to transfer. 

| bytesread is the number of bytes actually read. 

obyteswritten is the number of bytes actually written. 


om, Once the port has been opened, you can control it using a number of 


gp DosbevlOCtrl calls, which have the form 


anerr = DosDev!0Ctrl(data, paramlist, function, category, handle); 


a@ywhere 
data is a data value or the address of a data block. 
© paramlist is the address of an argument block. 
Brunction is a function code for that device. 
category is the category under which the function code falls. 
ge Handle is the device handle returned from the DosOpen call. 


There are 11 categories of functions that this call supports. Category | 
includes the calls to serial devices, so we will define SERIAL as 1. 


#define SERIAL 1 


) 


There are a large number of function codes in the serial category: the 
most important ones are listed in Table 15-3 
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Table 15-3. Serial Device Function Calls 


Set baud rate 
Start transmitting as if XON received 
Set break on 

Return stop, parity, data bits 


0x68 Return number of characters in 
receive queue 
0x69 Return number of characters in 
transmit queue 
Return COM error 


Return COM event information 
Return Control Block information 










Description 
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Setting the Baud Rate 


) 


This function accepts one argument in data consisting of the baud rate as an 
ry integer. The legal values are 110, 150, 300, 600, 1200, 1800, 2000, 2400, 
™) 3600, 4800,7200, 9600, and 19,200. 


J 


©) Setting Line Characteristics 


The line characteristics are passed in a 3-byte structure of the form 


o 
Struct LineChar 
“ begin 
o unsigned char databits, 
m par | ty 3 
stopbits; 
o end LineCtrl; 
On where 
m , 
databits can take on the values 5, 6, 7, or 8, for the number of data bits. 
o 
parity can take on the values 
oo 


0 no parity 
01 odd parity 
(2 even parity 
03 mark parity 
04 null parity 


Ait. 


@) stopbits can take on the values of 0, 1, or 2 for 1, 1.5, or 2 stop bits. 


J 


o™) The Device Control Block 


J 


The Device Control Block (DCB) is a structure consisting of timeout values, 
oy flags, and special characters. 
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struct DCB info 


begin 


USHORT writetimeout, 
readtimeout; 


UBYTE 


flagsl, 
flags2, 
flags3, 


errchar, 
breakchar , 


XONchar 


XOFF char ; 


end DCBinfo; 


™y, TS. TS, SR OOS TE, OS OS 


r 
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‘ read timeout in 0.01 secon 
‘ write timeout in 0.01 secg 4 
* DTRs GTS, DSR, DOD Contre] 

* XON/XOFF and RTS control ted 
* timeout processing 

‘ error replacement character 
* break replacement character 
* XON character 
‘ XOFF character 


@@¢ 


Function 0x53 allows you to set the read and write timeouts in the DC 


block as well as the settings of the handshaking modes as follows: 


flags 1 


flags2 


Setting of handshaking modes: 


bits 0-1 DTR control mode 
00 disable 
01 enable 
10 input handshaking 


11 invalid input resulting in general failure 


bit 2 reserved 


bit 3. enable output handshaking using CTS 
bit 4 enable output handshaking using DSR 
bit5 enable output handshaking using DCD 
bit 6 enable input handshaking using DSR 


XON-XOFF and RTS Control 


bit 0 


bit 1 


bit 2 
bit 3 
bit 4 
bit 5 
bits 6-7 


enable automatic 
XON /XOFF 


enable automatic 


XON/XOFF 


enable error replacement character 


remove null bytes 


enable break replacement character 


reserved 
RTS control mode 
00 disable 
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transmit flow control using 


receive flow control 
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01 enable 
10 input handshaking 
11 toggling on transmit 


flags3 timeout processing 


bit 0 enable write infinite timeout processing 
bit 1-2 read timeout processing 
00 invalid input resulting in general failure 
01 normal read timeout processing 
10 wait for something read timeout processing 
11 no wait read timeout processing 


ABATE 


o HANDSHAKING IN SERIAL COMMUNICATION 


©) Handshaking between serial devices is required if data can be sent to a 
™) device faster than it can be processed. For example, if you send data to a 
serial plotter, the plotter will take some time to actually move the pen and 
~’ draw the line. While the plotter may have some buffer memory, you can 
Oo eventually fill it up and the plotter must signal the computer not to send any 
™) data until it has room to store it. In the case of most serial plotters, the 
plotter raises the DTR signal when it can accept data and lowers that line 
when it cannot. 
In OS/2, the receive buffer has a length of 1024 bytes and the transmit 
™) buffer 128 bytes. Handshaking is necessary to assure that the receive buffer 
is not overfilled. There are a number of methods of performing handshaking 
using the signals listed above. 
When you open a COM port under OS/2, DTR and RTS are asserted by 
©) default, and output handshaking occurs using DSR and CTS. The levels of 
these signals and the hardware handshaking mode can be adjusted using the 
SetDCBInfo function 0x53. Exactly which one you choose depends on the 
\_ handshaking required by the device you are connecting to. 
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DTR Input Handshaking 


In DTR input handshaking mode, the device driver is high when the input 
queue is less than half full and is lowered if the queue becomes more than) 
half full. uy 


VL 
RTS-CTS and DTR-DSR &y 
When a device is ready to transmit a character in this handshaking mode, it 
asserts (sets high) the RTS (Ready to Send) pin. The receiving device may 
require that data only be transmitted when it is ready: that is, when it has 
set CTS (Clear to Send). In the simple transmit-receive sequence supported 
by DOS, RTS and DTR are both asserted before transmission and the func- 


tion waits for CTS and DSR before trying to read a character. WO 
VW 
XON-XOFF Handshaking YY 


The most common form of software handshaking is accomplished by having | 
the receiving device send an XOFF character (0x13) and send the XONW 
character (0x11) when it is again ready. This can be supported automatX 
ically within the COM driver by setting bit 0 of flags2 for transmit flow) 
control and setting bit 1 of flags2 for receive flow control. 


ww 

a, 
A SIMPLE COMMUNICATIONS PROGRAM © 
The program below sets the baud rate to 9600, enables DTR input hand 
shaking, and reads characters from the COM2 port, printing each on the_) 
screen. It also echoes the character back to the sending device, so we car 
illustrate communications output as well: 


VA 
SSCS see oe ese : : : KRKRAKRAK 
Dahle aah COMM Port Transmit and Receive Routine / 
#include <cdefs.h> ™ 
#define INCL BASE LU 


#include <os2.h> 
#include <stdio.h> 
#include <string.h> 


C 
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ALT. 


#define SERIAL 1 
#define SET BAUD Ox41 
define SET PARITY BITS 0x42 
ayjidef ine SET MODEM CONTROL 0x46 


#define SET DCB INFO 0x53 
define GET DCB INFO 0x73 
~ 


#define BUFLEN 256 


} 


Owvoid main() 
begin 


o USHORT hCom, action, baudrate; 
) char inbuf[BUFLEN]; 
wm int bytesread, byteswritten, err; 
@ struct DCB info 
mam  bdegin 
USHORT writetimeout, /* read timeout in 0.01 seconds */ 
Oo readtimeout; /* write timeout in 0.01 seconds */ 
om BYTE flagsi, /* DTR, CTS, DSR, DCD control a 
bd flags2. /* XON/XOFF and RTS control mode */ 
! Flags3, /* timeout processing i 
or» errchar, /* error replacement character f 
o> breakchar , /* break replacement characater “*/ 
XONchar , /* XON character mf 
o XOFF char ; /* XOFF character ay 
a end DCBinfo; 
Ovrr=DosOpen(''COM2"', &hCom, &action, 
am OL, 0, 1, 0x12, OL); /*read-write non shared*/ 


DP sitdicate = 9600; 
Merr=DosDevl0Ct1(OL, &baudrate, SET BAUD, SERIAL, hCom) ; 
err=DosDevlOCtI(&DCBinfo, OL, GET DCB INFO, SERIAL, hCom) ; 


OCBinfo.writetimeout = 3000;/*30 second write timeout =] 
OOCBinfo.readtimeout = 3000; /*30 second read timeout wy 
DCBinfo.flags1 = 0x02; /*enable DTR handshaking a7 | 
DCBinfo.flags2 = 0x03; /*no RTS handshaking */ 


a@err=DosDevl0CtI(OL, EDCBinfo, SET DCB _INFO, SERIAL, hCom); 
o 
a 
o 
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WY 
WY 
Ww 
i tk * Yo 
strcpy(inbuf,  ); /“initialize string ei 
while (inbuf[0] != ‘q') /*exit if ''q'' sent ap OD 
begin Ly 
err = DosRead(hCom, inbuf, 
1, &bytesread);  /*read a char if Y 
err = DosWrite(hCom, inbuf, a, 
1, &byteswritten); /*“write a char *y &Y 
inbuf[1]='\0'; /*make a l-character string “/ 
pritntcf(’ Ss ,inbuf): forint it */ @ 
end & 
end 
WW 
WS 
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LIST BOXES 
oo 


One of the standard types of dialog box elements is the /ist box, which 
allows you to select one from a series of listed items. You can also define a 
‘list box so that several items can be selected at once. A list box can contain 
oO up to 32K of characters in any number of lines of items. When a list box is 
(drawn that contains more items than can be displayed at once time, the 
scroll bars to the right of the box are activated, and you can scroll through 
the items by moving the scroll bar elevator or by clicking on the up or down 
\__/arrows at the top and bottom of the scroll bar. A typical list box is shown in 
©) Figure 16-1. 
ma Like all dialog box elements, a list box is just a special kind of window 
that receives and interprets special messages. During the initialization phase 
of the dialog box procedure, you fill the list box with items by sending it 
©) messages as follows: 


Mhvist = 
M) WinWindowFromID(hWnd, idList); /*list box window handle*/ 


WinSendD1g!temMsg(hWnd, /*dialog box window handle ay 
idList, /*id of list box in dialog box*/ 
LM_INSERTITEM, /*tell it to insert an item */ 


Bit ts. 


Vy 

WwW 
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Commands 


Lg 

7, 

Ky 

Cy) 

YO 

UO 

Ly) 

WO 

Hi therel Y 
, 

a, 

YU 

Figure 16-1. A typical list box, displaying filenames Ww 
(MPARAM)L1T SORTASCENDING, /*sort in ascending “ 
MPFROMP(text)); /*insert string o) 


Now, remembering that a dialog box is a window, it is not surprising that we 
manipulate it by sending it messages. To send them, we must obtain th 
window handle. In general, we only know the ID value that we assigne 
during creation of the dialog box using the dialog editor. However, the func 
tion WinWindowFromld will return the window handle given that ID value. 
Similarly, you clear out the list box by sending it thy 
LM_DELETEALL message 


/* delete all items from list box */ 
WinSendDlgltemMsg(hWnd, idList, LM_DELETEALL, OL, OL); 
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SELECTING A LINE FROM A LIST BOX 


If you point at any list box line with the mouse and click the left butto 
that line will be highlighted in inverse video. Then, if you select the "OK WY 
button or press Enter (if OK is the default), a WM_COMMAND messag_) 
WZ 
WZ 
Y/ 


wy 
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AA, 


will be sent to the dialog box window, with mp1 containing the DID_OK 
esmessage. Then, you can find out the number of the line that was selected by 
sending the list box the LM_QUERYSELECTION message 


on U J 
id = /*get the entry number*/ 

Oo SHORT 1FROMMR( WinSendD 1g! temMsg( 

oo hWnd, /*dialog window */ 

om FILELIST, /* list box 7d = */ 
| LM QUERYSELECTION,/*query a 

oO OL, /*no parameters */ 


omhen you can get the text of that line by sending the list box the 
LM_QUERYITMETEXT message 


a 
WinSendD1gltemMsg(hWnd, 
FILELIST, /*get the filename*/ 
Oo LM QUERYITEMTEXT, 
a MPFROM2SHORT(id, sizeof(filename)), 


MPFROMP( filename) ); 
om 


The other way that a line is often selected in a list box is by double clicking 

on it. In this case the message WM_CONTROL is posted to the dialog box, 

vith mpl set to LN_ENTER. When you receive this message you simply 
yost the WM_COMMAND message with mp1 set to DID_OK. 


My:ase WM CONTROL: 


>) switch(SHORT2FROMMP(mp1)) /*look for double click * f 
begin 
case LN ENTER: /*comes from a double click*/ 
WinPostMsg(hWnd, 
WM COMMAND, /*post a DID OK message a 
MPFROMSHORT(DID OK), 
OL); 
return((MRESULT)TRUE); /*message processed x / 
break; 
end 
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FILLING A LIST BOX WITH FILENAMES 


You can use the DosFindFirst and the DosFindNext calls to get filenames 
from the current directory. The DosFindFirst call has the form 


rcode= 


DosFindFirst(filename, Shandle, attrib, &rbuf, 


where 


filename 


& handle 


attrib 


& rbuf 


buflen 


& srchent 


NULL 


The FILEFINDBUF structure has the form 


buflen, &srchcnt, NULL); 


60000000006 


is the filename string to match. You can use the "*" and(_) 
"2" wildcard characters to specify the name. A path 
specification may also be part of the name string. 


is a pointer to the handle for this directory operation. If 
you set the handle to Oxffff, a handle is allocated and 
returned in this address. VJ 


specifies the file attributes to search for. Each bit set 
searches for that file type in addition to normal matching\_» 


filenames. Cc) 
0x0001 read only files Ly) 
0x0002 hidden files 

0x0004 — system files Y 
0x0008 volume labels VU 
0x0010 subdirectories ey 


is the pointer to a result buffer, consisting of the struct 
ture FILEFINDBUF shown below. ‘oe 


is the length of the result buffer. os, 


is the number of matching entries requested. On returnw 
this number of entries is placed in  successive_) 
FILEFINDBUF structures starting at the address speci- 
fied in rbuf. 


is a reserved long argument. 
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typedef struct FILEFINDBUF { /* findbuf a 
FDATE fdateCreation; /*creation date a 

on FTIME ftimeCreation; /*creation time a | 
am FDATE fdateLastAccess; /* last atcess date | 
| FTIME ftimeLastAccess; /*last access time a 
© > FDATE fdateLastWrite; | /*date of last write */ 
™  FTIME ftimeLastWrite; /*time of last write */ 
ULONG cbFile; /*file size in bytes “*/ 

% ULONG cbFileAlloc; /“allocated file size “/ 
O) _USHORT attrFile; /*file attribute bits */ 
a UCHAR  cchName; /*length of filename “*/ 
| CHAR = achName[ 13]; /*filename *Y 


©} FILEFINDBUF; 


Upon return, rcode contains 0 if the call was successful, and otherwise con- 
O™tains an error code. 
The DosFindNext uses the handle returned above to find additional 
matches to the previously specified filename and attributes: 


an’ code = 
DosFindNext(handle, &rbuf, buflen, &srchcnt); 


where all the arguments have the same meaning as above. Note that, as 
\ before, rcode contains 0 if the search is successful and non-zero if no more 
files can be found that match the filename and attributes. 


a 


Getting Subdirectory Names 


The DosFind... calls will match all the files that have the path and name 
specified in the filename argument. Thus, to find all files with the .DAT 
(&xtension, you set the filename to "*.DAT". If you have the subdirectory bit 
samset as well, the subdirectory names in this path will also be found, including 
the “..” and “.” entries for the parent and current directories. While it is 
easy to tell that a name represents a subdirectory if it is named “..” there is 
yo way to tell whether a name such as DATA is a file or a subdirectory. To 
emaistinguish them, we will intercept them and enclose the names in brackets: 


La*] 
[ DATA] 


ALAS. 
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using the following simple code: 


if (rbuf.attrFile == SUBDIR) then 
begin /*“if this is a subdirectory*/ 
strcpy(filename, ''[''); 
strcat(filename, rbuf.achName); /*enclose name in [] “*/ 
strcat(filename, '']'); 
end 
else 
/*“otherwise just put name in list*/ 
strcpy(filename, rbuf.achName) ; 


The complete routine for filling the list box 1s shown below 


void FillListBox(HWND hWnd, int idList, char “fi lemask) 


y a i a ae ae ae a tg * jf 
/* Fills a list box having the id ‘‘idList'' which is a of 
/* child of the dialog box window ''hWnd'' with all a 
/* filenames which match the filemask. mf 
/* saad dae ent sR wah ac tgat aed usa cat ecules tte os kisses hc cc La a cess Nac el ce bh at pM ee Na * / 
begin 

HWND hList; /*list box window handle a 

FILEFINDBUF rbuf; /*file find buffer structure*/ 

USHORT retcode, searchcount, 

attrib; 
HDIR DirHandle; /*“handle to the directory “*/ 


char fi lename[ 80]; 


hList = 
WinWindowFromID(hWnd, idList); /*list box window handle”/ 
WinEnableWindowUpdate(hList, 
FALSE); /*no update till filled */ 

WinSendD1gltemMsg(hWnd, /*delete all in listbox */ 

[aL t(Shs 

LM DELETEALL, 

OL, OL): 


/*search for matches to filename mask”*/ 


DirHandle = Oxf fff; /*return new handle here */ 
attrib = SUBDIR; /*normal files mf 

/* and subdirectories a 
searchcount = 1; /*number of matching i 
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/* entries to find a 


retcode = 
DosFindFirst(filemask, /*find first match 
EDirHandle, 
attrib, &rbuf, 
sizeof(FILEFINDBUF), 
&searchcount, NULL); 


if (retcode == NULL) then /*there was one match a 
begin 
do 
begin 
if (rbuf.attrFile == SUBDIR) then 
begin 
strepy(filename, ''[''); /*if this is a subdir ay 
strcat(filename, 
rbuf.achName) ; /*enclose name in brackets*/ 
strcat(filename, '']'); 
end 
else 


strcpy(filename, 
rbuf.achName); /*else just put name in list*/ 
WinSendD1Ig!ltemMsg(hWnd, 
idList, 
LM INSERTITEM, /“insert in list box*/ 
(MPARAM)LIT SORTASCENDING, 
MPFROMP(filename) ); 


'}0GGGGGGGGGGGGGGOGOGOGOOGGGOD 


retcode = 
DosFindNext(DirHandle, 
&rbuf, /*look for another match = 
sizeof(FILEFINDBUF), 
&searchcount); 
end 
while(retcode == NULL); /*loop until none are found */ 
) end 
ay WinShowWindow(hList, TRUE); /*now display this list box */ 


end 
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CALLING THE DIALOG BOX 


In calling a dialog procedure that will return a filename, we need to use tho” 
last argument of the dialog box call to pass the address where the filenam(__ 
will be returned. Then if the call returns TRUE, we know that we have ¢ 
valid filename in that string; if it returns FALSE, we know there is not a 


valid filename. VY 
rcode = Y 
WinDIgBox(HWND DESKTOP, WV 
hWnd, /*“parent and owner windows “/@ 
FileDlgProc, /“address of dialog procedure*/ 
NULL, /*look in the resource file *“/W 
FILEBOX, /*“id of dlg in resource file */ 


(PVOID)mstring); /*address of string to return*/ 


if (rcode) then 
open file(mstring); /*open that file if OK pressed”/ 


C 


Recognizing a Subdirectory 


@@« 


If we select a subdirectory, we don’t want the dialog box to exit and returw 
that filename. Instead, we want to change to that subdirectory and show they 
files in it. It’s easy to recognize these subdirectories, since we have enclose? 
them in brackets: we simply see if the first character of the string is a 
bracket, and if it is, we change to that subdirectory using the DosChDir call 


if (localname[0] == ‘[') then /*if this is a subdir*®/— 
begin ‘eo 
strcpy(filename, localname + 1); /*remove first [ & 
len = strlen(filename) ; /*get length a(S 
filename[len-1] = ‘\0'; /*remove last ] * 1S 
DosChDir(filename, OL); /*change directory “*/ 
FillListBox(hWnd, FILELIST, ''*.*''); /*refill list box*/ 
end 
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ALi. 


The Dialog Box Procedure 


Boia FillListBox(HWND hWnd, int idList, char *filemask) 


XL 


* Fills a list box having the id ‘'idList'' which is a 


/* child of the dialog box window ''hWnd'' with all af 
©Y* filenames which match the filemask * ff 
ee */ 

begin 

HWND hList; /*list box window handle oF 
™) FILEFINDBUF rbuf; /*file find buffer structure*/ 
o> USHORT pastas searchcount, 
attrib; 
O) HDIR DirHandle; /“handle to the directory */ 
a char filename[ 80]; 
O List = WinWindowFrom!D(hWnd, 
idList); /*list box window handle  “*/ 
WinEnableWindowUpdate(hList, 
FALSE); /*no update till filled | 
aw inSendD1gltemMsg(hWnd, /*delete all items from listbox*/ 
idList, 
“ LM DELETEALL 
a. bi The 
/*search for matches to filename mask*/ 
OVirHandle = OxfffFf; /*return a new handle here */ 
mattrib = SUBDIR; /*normal files and subdirs */ 
searchcount = 1; /*number of matching entries*/ 
ametcode = 
DosFindFirst(filemask, &DirHandle, 
attrib, €rbuf, 
m sizeof (FILEF|INDBUF ), 
> &searchcount, NULL); 
OF (retcode == NULL) then /*there was at least one match*/ 
m begin 
— do 
begin 


if (rbuf.attrFile == SUBDIR) then 


on, 
o~ 
cy 
m 
oO 
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begin 
strcpy(filename, ''[''); /*if this is a subdir 
strcat(filename, 


©@eeo06é 


rbuf.achName); /*“enclose name in brackets*/ | 


strcat(filename, '']''); Y 
end i, 
else | 
strcpy(filename, Y 
rbuf.achName) ; /*else just put name in list*/ WW 
WinSendD1gIl temMsg(hWnd, & 
idList, 
LM INSERTITEM, /*“insert in list box*/ 
(MPARAM)LIT SORTASCENDING, 7) 
MPFROMP( filename) ) ; | 
retcode = Y 
DosFindNext(DirHandle, WJ 
erbuf. /“look for another match “*/ 
sizeof(FILEFINDBUF) , Y 
&Searchcount); a, 
end C) 
while(retcode == NULL); /*“loop til no more found “*/ 
end wy 


WinShowWindow(hList, TRUE); /*now display this list box*/ & 
end 


/ KKKEKKKKKKKAERKKKRKAKRKKKKKRKRKRKRKKREKRKRERRRKRRKREEKREKRERRRKRKRKR:E / er, 
MRESULT EXPENTRY FileDlgProc(HWND hWnd, USHORT msg, _/ 

MPARAM mp1, MPARAM mp2) | 
/* ast nwt Dc ese a I pc eg i gc a a ae al a * Ww 
/* Dialog box procedure to fill a list box with a */ @ 
/* filename and return the selected filename in the ae 
/* argument pointer If a subdirectory is selected, ip 
/* the list box is refilled with the files in that */ @ 
/* subdirectory Bs 


begin 
int id, attrib, len; 
static char localname[80], “filename; 


eeeeeeeded 
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a@mswitch (msg) 
begin 
Okase WM_INITDLG: 


OM FillListBox(hWnd, 

PILES. > s /PPiit Vist box *Y 
es filename = (char *)mp2; /*pointer to arg */ 
O)  WinPostMsg(hWnd, WM BUTTONIDOWN, 
am OL, OL); /*activate window */ 

return( (MRESULT) TRUE) ; /*message processed*/ 
om break; 
o- 


case WM COMMAND: 
switch( SHORT 1FROMMP (mp1) ) 


begin 
case DID OK: 
id = 
WinSendD1gl temMsg( hWnd, 
FILELIST, 
LM QUERYSELECTION, 
OL, OL ); 
if (id == LIT NONE) /*if no file highlighted*/ 
begin 
strcpy(filename, '"');  /*set to no length af 
WinDismissD]g(hWnd, 

FALSE); /*and return FALSE ae 
return( TRUE); /*“message was processed */ 
end 

else 
begin 
WinSendD1gltemMsg(hWnd, 
FILELIST, /*get the filename mf 


LM QUERYITEMTEXT, 
MPFROM2SHORT(id, sizeof(localname)), 
MPFROMP( localname) ); 


/*copy filename to return it *Y 
strcpy(filename, localname) ; 
end 
if (localname[0] == '[') then /*if a subdir */ 
begin 
strcpy(filename, localname + 1);/*remove first [*/ 
len = strlen(filename) ; /*get length a 


'}ddGGGG80G0G8808GG8OGOOO 


236 USING LIST BOXES TO GET FILENAMES 


Oeé 


filename[len-1] = ‘\0'; /*remove last ] */ 
DosChDir(filename, OL); /*change directory*/ ™ 
FillListBox(hWnd, ‘oe 
PILELIST, at de refill Tist ber”? | 
end Y 
else WW 
WinDismissD]lg(hWnd, TRUE); /*return true eae 
return( TRUE) ; /*“message processed*/ 
break; WwW 
. _O 
case DID CANCEL: /*Cancel pressed i ae 
strcpy(filename, '); /*set filename to none*/ 
WinDismissDIg(hWnd, FALSE); /*and return false  */() 
return( TRUE); 
break; Y 
end Y 
case WM CONTROL: yaad 
switch(SHORT2FROMMP (mp1) ) /*look for double click*/ WW 
begin ‘oe 
case LN ENTER: /*mesg from a dbl click*/ .. 
WinPostMsg(hWnd, YW 

WM_COMMAND , /*post a DID_OK message*/ ) 

MPFROMSHORT(DID OK), 

OL); Y 
return((MRESULT ) TRUE /*message processed “/@ 
break; 

default: 
return(WinDefD1lgProc(hWnd, msg, mpl, mp2)); 
end 
default: 
return(WinDefD1lgProc(hWnd, msg, mp1, mp2)); 
end 
return(FALSE) ; 


end 
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Adding Drive Names to the List Box 


You can find out which drives are active in a system by using the 


osQCurDisk call 
DosQCurCDisk(&curdisk, &bdisks); 
a 
where 
o 
ak curdisks The drive number of the current drive, where A: is 1, B: 
is 2, etc. 
fy 
aa aisks A bit map of the currently installed drives, where the 
Cy lowest bit represents an A: drive and the 26th bit a Z: 
om, drive. 


nen, to insert a drive letter enclosed in hyphens, you write the following: 


Ossi = 1h /*set mask to bit 0*/ 
Mor (i = 0; i < 26; i++ ) /*\o0p thru up to Z:"/ 
begin 
if (bdisks AND mask) then 
begin 
a name(O] = - ; /*start string with dash*/ 
~ name[1] = (char)('A' + i); /*calculate drive letter*/ 
“y name[2] = ‘-'; /*terminate with dash “*/ 
MM name[3] = ‘\0'; /*string null terminator*/ 
~ WinSendD1g!temMsg(hWnd, /“insert drive name “J 
*, idList. 
o LM INSERTITEM, 
> LIT SORTASCENDING, 
name); 
O) mask <<= 1; / shift mask 1 place lerft*/ 
Om end 
end 
a, 
aA you select a drive letter, you must change to that drive using the 


JosSelectDisk call 


6600000 


a, 
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| 
if (localname[0] == ‘-') then ¢ 
begin | 
disknum = localname[1] - 'A'; /*calculate drive number*/ WW 
DosSelectDisk(disknum): /*change to that drive ‘/@ 
FillListBox(hWnd, 
PILELIST, 9"); /*refl lt list: box xO 
end | 
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1/7 Graphics Metatiles and 
segments 


Sit TTY 


OWhen you issue any of the Gpi calls to draw on the screen or any other 
@mevice, a series of 16-bit codes called graphics orders can be generated that 
escribe these drawing functions in a compact way that can make redrawing 
“very fast. These orders can be stored in a file called a metafile or stored in 
ibles associated with a normal presentation space called graphics segments. 


os 


OVIETAFILES 

Oo 

Sraphics metafiles can be used to save and replay complex graphical oper- 
ations as rapidly as possible. They are device independent and can be inter- 

~ ureted by computers attached to other higher-quality printing and plotting 

Myevices to make publication-quality copies. Since metafiles contain a list of 

cwaphics orders, they are independent of the resolution of the device and 

they can be displayed on displays of any convenient resolution. 

Once you have saved a metafile on disk, you can use the OS/2 
© JICPRINT and PICSHOW programs to display and print these metafiles 
om any plotter or printer supported by OS/2. 
on You can use metafiles to save and display complex drawings such as 

»-dimensional perspective representations, logos, or multiple plots on a 
Ongle screen. You can save metafiles as actual disk files to read in and 


o™splay later, or you can just use them as tables of data to display inside your 
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program. This latter approach overlaps with graphics segments, which w 
will discuss later in this chapter. 


©8600 06 


Creating a Metafile 


OS/2 PM considers a metafile to be a device just as a printer or a plotter i_ 
a device, and you must create a device context for one just as you do for & 
real device. 


WY 
/* define a device open structure -- */ SZ 
/* ~~ only ''DISPLAY'' is needed*/ ot eel 
DEVOPENSTRUC dop = Ly 
{OL DISPLAY, OL, OL, “comments ,0L ,0L.,0L,0L BO 
hDC = WY 
DevOpenDC(hAB, OD METAFILE, &) 
wa" /*open a metafile DC */ 

cL, Y 
(PDEVOPENDATA)&dop, C) 

NULL) ; | 
W/ 


The DevOpenDC call creates a device context for a device having the charag 
teristics defined in the DEVOPENSTRUC structure. However, the struc- 
ture actually expected by this call isa DEVOPENDATA structure, which VY 
the same thing, but must be cast to this type to avoid compilation errors. I\v 
this structure, the only relevant field is the device driver name field wher) 
we indicate that the driver name is “DISPLAY.” This means that the 
metafile is generated using the current display driver DISPLAY.DLL. Th 
remaining fields are unused. VU 

Once a metafile device context is created, you create a metafile presenta_) 
tion space associating this device context with it. It is also useful to create 1 
using the current window size: 


f 


a : : 5 wD 
WinQueryWindowRect(hWnd, &rc); /“get current window size “/ 
siZ2.cx = Te. XR igits /*copy into size structure*/ 
SIZ.cy = rc. Vlop; & 


hPSmeta = GpiCreatePS(hAB, hDC, 
ESiZ, /*create a metafile PS 
PU PELS | 


* / WS 


Y 
WV 
Ss 
7 
YW 
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GPIA ASSOC); 


Then, you simply do all the drawing you need into this metafile, calling all 
qpxour drawing routines with the hPSmeta presentation space handle. 


aM rawscreen(hPSmeta) ; /*draw everything into this PS*/ 


) Finally, you disassociate the presentation space from any device, and 
amslose the device context, which returns the handle to the metafile. Then the 
GpiSaveMetaFile call is used to save the metafile to a disk file. This call will 
snly actually save the file if no file by that name already exists, so it is usual 
» delete any file of that name before saving it. When you issue the save 
emetafile call, the memory version of this metafile is automatically deleted 
and the hMF handle is no longer valid. 


a&piAssociate(hPSmeta, 


| (HDC )NULL); /*disassociate from display*/ 
O MF = DevCloseDC(hDC); /*here is where the af 
om /*metafile handle comes in */ 
strcpy(tname, ''META.MET''); /*get a meta file name a 
~osDelete(temp_name, OL); /*delete any previous file */ 


(™piSaveMetaFile(hMF, tname); /*use it to save metafile */ 
he complete routine for saving a metafile is show below: 


@Psid savemeta(HAB hAB, HWND hWnd) 
Be Pe sn ee la rN ee oe te ee A et a sc / 


L 1 


This routine creates a metafile, draws into it, and / 
“saves it as ''META.MET''. The handle to the current i 
i 

/ 


12 


anchor block is hAB and the handle to the current 
window is hWnd 


To ee 


ee Nee ee Pe Nee ee ren eR ete ae eee eA aE CR eR Tee Tee Toe Ee *Y 
gin 
HDC hDC; /*device context a 
SIZEL siz; /*size structure Af 
char tname[ 80]; /*file name mf 
RECTL. res /*rectangle structure “*/ 
HPS hPSmeta; /*metafile PS */ 
ON HMF AMF ; /*metafile handle a 
DEVOPENSTRUC dop; /*device open structure*/ 


> 


sees 
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WinQueryWindowRect(hWnd, &rc); /*get current window size” 
siz.cx = rc.xRight; /*copy into size struct 
siz.cy = re.ylop; 


se 


dop.pszDriverName = ''DISPLAY''; /*“display device driver 
dop.pszComment = ''comment''; 
hDC = DevOpenDC(hAB, 

OD METAFILE, 


scl 


3 


ny 


SOCHOOHHSOHSOOHOOC ES 


/*“open a metafile DC 


ks 
(PDEVOPENDATA) &dop, 
NULL) ; 
hPSmeta = GpiCreatePS(hAB, hDC, 
esi 2. /*“create a metafile PS 
PU PELS -| 
GPIA ASSOC); 
drawscreen(hPSmeta) ; /*“draw everything into this PS*/ 
GpiAssociate(hPSmeta, 
(HDC )NULL) ; /*disassociate from display */_) 
hMF = DevCloseDC(hDC); /*here is where the metafile */, 
/* handle comes in Td 
strcpy(tname, ''META.MET''); /*get a meta file name * |e 
DosDelete(tname, OL); /“delete any previous file a 
GpiSaveMetaFile(hMF, tname);/*use it to save the metafile*/™ 
GpiDestroyPS(hPSmeta) ; /*“destroy the meta PS *hS 
end YY 
VY 
PLAYING BACK A METAFILE iC) 


A metafile stored in memory after a DevCloseDC call returns its handle ca 
be played back immediately using the GpiPlayMetaFile call. Playing back 
metafile stored on disk amounts to loading the metafile, which returns t\_) 
metafile handle, and then calling the playback function, which has the forrr 


GpiPlayMetaFile(hPS, hMF, optionsize, 
options, &Segcount, dsize, desc); 


where 
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am 
OPS is the presentation space where the playback is to occur. 
O\MF is the handle to the metafile. 

sptionsize is the number of entries in the options array. 

uptions is an array of long integers describing the transform- 

ations transformations, font id’s, reset status, playback 

a, status, and color tables. 
»gcount is the count of any segments in the metafile that are 
> renumbered. 
size is the number of bytes in the desc string. 
vse is the comment string stored with the metafile. 


a this example, we will load the option array with all the default values. 


j 


void playmeta(HAB hAB, HPS hPS, HWND hWnd) 


a se eee ee *Y 
ak" This routine loads and plays back a metafile a 
/* "'META.MET'' into the presentation space specified by “*/ 
O} the handle hPS. Boston fans can rename the file if a 
ao desired. The anchor block is hAB and the handle to 47 
a the current window is hWnd. a A 
ae ERR Oe Ie a ve ee AAI et ae EE SRE CLE ROE eT el PRA TCS CN? ee REESE Eee sc / 
Ogin 
HDC HDC; 
A) SIZE Bz 
oo char “tmppt, desc[256], buf[80]; 
ra RECTL re; 
HMF hMF: 
‘al, ine err? 
™, long options[PMF COLORREAL|IZABLE + 1], segcount; 
Or = 
) GpiLoadMetaFile(hAB, 
~~ "META.MET"') ; /*load the metafile */ 
_ptions[PMF SEGBASE] = OL; /*set up all defaults*/ 


@ptions[PMF_LCIDS] LC DEFAULT; 
uptions[PMF RESET] RES DEFAULT; 
rua - - 


(ptions[PMF_LOADTYPE] = LT DEFAULT; /*in the option array*/ 
| 
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options[PMF SUPPRESS] = SUP NOSUPPRESS; 
options[PMF COLORTABLES] = CTAB DEFAULT; 
options[PMF COLORREAL|! ZABLE] = CREA DEFAULT; 


060600 @ é 


GpiPlayMetaFile(hPS, /*now play it in the PS*/ 
hMF , W 
PMF COLORREAL|! ZABLE, Ky 
options, &segcount, an 
256L, desc); w 
| _@ 
err = WinGetLastError(hAB); /“check for error et 
if (err != 0) then basal 
begin a, 
sprintf(buf, Error = %x ,err); + 
WinMessageBox(HWND DESKTOP, hWnd, buf, 
Metafile error’, 1, MB OK); YW 
end & 
end 
/ 
YW 
GRAPHICS SEGMENTS se 


OS/2 provides a way for you to store the same graphics orders generated t 
metafiles in graphics segments, in your presentation space so they can & 
redrawn rapidly. These segments can only be created and stored in norme’ 
presentation spaces, but should in theory provide a way for you to vedra™ 
complex graphics quickly. Segments also provide a way for you to selew 
drawing elements with the mouse and see if they have been picked using co{_) 
relation function calls. Whether the segment method is in fact faster 7) 
dependent on the type of display you are using and on the version of the | 
OS/2 display device driver. YY 
Graphics segments have a number of attributes that you can use \_) 
create and identify them. These include wy 


C 


chained A chained segment is logically connected Ly) 
preceding segments. If you do nothing t- 
change it, all segments are chained and ca 
be drawn in a single GpiDrawChain call. | 


re 
‘7s 
, 
| 
WY 
Y 
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fast-chaining Fast-chaining segments do not reset the 
graphics attributes to their default values. 
This is also a default attribute for all seg- 
ments. 


yee 


ynamic Dynamic segments are a group of segments 
designed to be drawn last and erased and 
moved as necessary. This is usually done 
using the segment transform matrix, which 
we will discuss later: 


Lee e @. 


etectable If this attribute is set, then this segment can 
| be picked by clicking on it with the mouse. 
This attribute is usually set to FALSE and 
must be turned on if you want to be able to 


pick segments. 


Segments with the visibility attribute set to 
FALSE are not drawn. Normally segments 
are defined as visible. 


22Q999 


apr opagate visibility If one segment is made visible then any seg- 
ments it calls will be visible too. 

am 

su epaeate detectability If one segment is detectable then any seg- 


ments it calls will be detectable too. 


You can create segments that either are identified with numbers or have 
Nero id’s. You number segments if you wish to refer to them again individ- 
mally, and you leave the identifiers as zero if you will only display them as a 

roup. Segments that you wish to pick out individually using the mouse and 
che GpiCorrelate function must have non-zero identifiers. A simple segment 
Oreation routine might be 


@), i opensegment (hPS, segnum) ; /“open a segment my 
@pt.x = 50; pt.y = 50; 
piMove(hPS, &pt); /*move to corner of box */ 


Sto = 100; pt.y = 100. 

(%piBox(hPS, DRO OUTLINE, &pt, 

NULL, NULL); /*draw the box 
upiCloseSegment (hPS) ; /*and close the segment * 
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Then, any time you wish to draw the items in that segment, you can simply 
use the call 


GpiDrawSegment(hPS, segnum) ; 


o¢ 


If you create a series of segments having separate numbers or all having zero 
identifiers, they are by default chained together, and you can draw them all 
at once using the call 


GpiDrawChain(hPS) ; /*draw all the chained segments*/ 


PICKING (CORRELATING) SEGMENTS 


66 e@ 


We can find out if the mouse pointer is touching a line belonging to a givenY 
segment by using the mouse coordinates as input to the 
GpiCorrelateSegment or the GpiCorrelateChain calls 


ee, 

hits = GpiCorrelateSegment(hPS, segnum, type, &pt, @ 
maxhits, maxdepth, tags); 

hits = GpiCorrelateChain (hPS, type, &pt, WY 

maxhits, maxdepth, tags); &y 

where i, 

hits is the number of hits found. a, 

segnum is the segment number to test for a hit. Y 

type is either PICKSEL_VISIBLE or PICKSEL_ALL™ 

depending on whether only detectable segments or alwy 

segments are to be tested for a hit. iy 

& pt is the address of the POINTL structure containing thi 

coordinates to be tested for a hit. Ly) 

maxhits is the maximum number of hits that may be returned 1i_) 

the tags array. Y 

maxdepth is the maximum number of pairs of segment number) 


and tags that may be returned for each hit. 
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is an array of long integers equal in size to 
2*maxhits*maxdepth. For each hit, this array contains a 
pair of values consisting of the segment number and the 
segment tag. Each segment may contain one or more 
segment tags and if several drawing elements having dif- 
ferent tags intersect the pick aperture, several hits are 
produced. 


93999999599 


m>egment Tags and Labels 


YY ou can tag each segment with one or more tag values using the 
Om GpiSetTag(hPS, tagnum); 


call. Tags may be any non-zero identifier. A segment initially has a tag of 
zero and such segments are not picked when the segment is correlated. 
OmThere can be several tag values within a segment and the latest one is the 
enone returned by the correlate call. 
Segment /abe/s are set with the 

GpiLabel(hPS, labelnum); 

a, 
ayeall. Labels need not be unique nor non-zero, and are not returned by the 

correlation operation. Instead, they are used to search out parts of a segment 


you wish to edit or delete. 
am, 


CREATING AND PICKING SEGMENTS 
m7 


alo create and display segments that you can pick, you need to 


oy 1. Get a window Device Context. 
~@, 2. Create a normal Presentation Space. 
3. Set the drawing mode to retain. 
el’ 
4. Delete any previous segments. 
)5. Set the segment attributes to detectable. 
6. Open the segment. 
7. Tag the segment with a non-zero value. 


8. Do the drawing inside the segment. 


) 


) 
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9. Close the segment. 


You can do all of this at the time the window Is created by using 


case WM CREATE: 


Sz.cx = WinQuerySysValue(HWND DESKTOP, 

SV_CXFULLSCREEN) ; 
sz.cy = WinQuerySysValue(HWND DESKTOP, 

SV CYFULLSCREEN)>; 
hDC = WinOpenWindowDC (hWnd) ; /*get a window DC */ 
hPS = GpiCreatePS(hAB, hDC, &sz, PU PELS | GP IA ASSOC) ; 
GpiSetDrawingMode(hPS, DM RETAIN); /*retain drawing ra 


GpiDeleteSegments(hPS, IL, 
segnum =1; 
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Ceeeeeeeeoecocecs 


/*“delete prev. segs * 


/*1st nonzero segment*/ 


GpiSetInitialSegmentAttrs(hPS, WW 
ATTR DETECTABLE, 
ATTR ON); ” 
GpiO0penSegment(hPS, segnum) ; /“open the segment */ Wy 


GpiSetTag(hPS, segnumt+) ; 


pi.x = SOs pi.y = 50; 
GpiMove(hPS, &pt); 


pt.x = 100; pt.y = 100; 
GpiBox(hPS, DRO OUTLINE,épt, 
NULL, NULL); 


GpiCloseSegment (hPS) ; 
GpiO0penSegment(hPS, segnum) ; 
GpiSetTag(hPSs, Segnum++) ; 


pE.x = 1503 pt.y = 150; 
GpiMove(hPS, &pt); 
pt.x = 200s pt.¥ = 200; 


GpiBox(hPS, DRO OUTLINE, &pt, 


NULL, NULL); 


pts = 1753 pt.y = 30; 
GpiSetTag(hPS, 12L); 
GpiMove(hPS, &pt); 
pt.x = 250; pt.y =175; 
GpiLine(hPS, &pt); 
GpiCloseSegment (hPS) ; 
break; 


/*set a seqment taq */, 
g J VW 


/* to nonzero oF | 
/*lower box corner “/ Ww 
2 4 
/“upper box corner “*/ 
OS | 
WY 


/*‘end of first segment*/ 
/*second segment <4 
/*tag with segment num*/\/) 


/*lower box corner /@ 
/*“upper box corner * | @ 
WY 
/*also draw a line 7 ed 


/*with another tag value*/( ) 
/*end of line */ 


/*end of 2nd segment a 
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(Then, since the segments are all chained together by default, drawing the 
apscreen amounts to a single call plus validating the region when you are done: 


amcase WM PAINT: 
WinQueryWindowRect (hWnd, 


ere): /*get current window dimensions*/ 
WinFillRect(hPS, &rc, 

CLR WHITE); /*fill it with white */ 

GpiDrawChain(hPS) ; /*draw entire segment chain a 


WinQueryUpdateRect (hWnd, é&rc); 
WinValidateRect(hWnd, &rc, 
TRUE); /*validate entire region 


reouo 


break; 


Finally, you can simply intercept the WM_BUTTONIDOWN mes- 
sages and see if a segment has been selected by using the correlate chain call 


case WM BUTTONIDOWN: /*when button is pressed*/ 
>) pt.x = SHORTIFROMMP (mp1); /*get its coordinates ~*/ 
~ pt.y = SHORT2FROMMP (mp1) ; 
‘4 hits = GpiCorrelateChain(hPS, /*look for any hits my 
a PICKSEL VISIBLE, &pt, 
pn 2L, IL, tags); 
if (hits > 0) then /“if there are any hits “/ 
on begin /*say so in a message box*/ 
sprintf(buf, ‘Hits = %d',hits); 
sprintf(hitbuf, ‘Segment = %ld %ld', 
(“y tags[0], tags[1]); 
a, WinMessageBox(HWND DESKTOP, hWnd, 
buf, hitbuf, 1, MB OK); 
“)y end 
a™ break; 
a 


The Pick Aperture 


“Normally, the size of the region on the screen that is considered to be 
picked, called the pick aperture, is the size of a character box for that 
©) display type. You can make this aperture smaller or larger using the call 


) GpiSetPickApertureSize(hPS, options, &size); 
a 
o 
ao 


o™ 
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where 


&60Oeee 


options can be either PICKAP_DEFAULT, in which case the size_) 
parameter is ignored, or PICKPAP_REC, where the size value 


is used. 

& size is the address of the size of the aperture in a SIZEL structure. 
The members of the structure are the long integers size.cx 
and size.cy. ws 

You can also set the pick aperture position without waiting for a mouse click 

by using the call WwW 

GpiSetPickAperturePosition(hPS, &pick); Y 


where pick is the address of a POINTL structure. Once you have set this 
aperture position yourself, you can actually do any drawing you want with 
the Gpi functions and examine their return codes. If any Gpi function 
returns the value GPIT_HIT then that drawing passed through the current, 
pick aperture position. i 
/ 
a, 
CY 
Once you have created a complex graphics segment, you might find it usefull_> 


EDITING SEGMENTS 


to change some small attribute, such as the color or line type, and redraw it 
without having to reconstruct the entire segment. You can do this if you 
label the positions in the segment with unique values using the GpiLabel call 
when you create it. Then you can reopen the segent and position the element. 


pointer at that label by making the calls C) 


GpiSetElementPointerAtLabel(hPS, 
label); /*find label and “*/ 
GpidffsetElementPointer(hPS, 1L); /*increment pointer*/ Y 


The first call sets the element pointer to the position containing the label and— 

the second increments to the point just beyond it. WY 
Once you have located the labelled position in a segment, you can insert) 

an element or replace the element at that position by simply making the news ) 

function call. Elements are either inserted or replaced depending on the state 

of the call | 


666 O6¢ 


GRAPHICS TRANSFORMS 251 


AAT 


GpiSetEditMode(hPS, mode); 


“where mode can be either SEGEM_INSERT or SEGEM_REPLACE. The 
mdefault value is insertion. 


om 
oGRAPHICS TRANSFORMS 


You can draw a segment once using the draw segment or draw chain calls, 
but it is useful in technical drawing to be able to draw several copies of the 
qmsame picture when each represents a repeating element of a more complex 

drawing. OS/2 provides the ability to translate, scale and rotate any 

segment intwo dimensions by multiplying it by a transform matrix. While 
moving the segment on the screen is actually an addition process, the scaling 
opand rotation operations are multiplication processes. In order that all of the 
operation be representable in a single matrix operation, the definition of 
each x,y data pair has been expanded to have a third coordinate, which is 


always 1. For linear translation of data the matrix is 


an 

1 0 0O 
("y ivevisiegil ot 2 
fh rT, tT, 1 
om 
omfor scaling, the multiplication matrix 1s 
‘ab S.0 0 
ab [xy 1J=[xy 1] ]o s, 0 
a 00 |] 
a, 


and for rotation, the matrix is 


cos@ sin@ 0 
[x’y 1] =[Lxy1]]—- sin @cos@ 0 
0 0 l 


»oe¢5 


yin general, the equations for scaling, translation, and rotation are 


x’ =Ax+Cy+E 


38ee8e 
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y =Bx+Dy+F 


where 
AB 0O 
[xy 1l]l=Lxy1] CD 0 
EF | 


6000086006 


To summarize, the translation values are represented by E and F, the, 
scaling values by A and D, and the rotation values by A, B, C, and D. To 
make these operations as rapid as possible, they are all carried out in fixed\” 


¢ 


point using a 32-bit representation in which 16 bits represent the integer\_> 
part of the number and 16 bits the fractional part. Thus, 1.0 is represented 
as 0001 0000 or 65536L. The matrix has been defined as a 9-element struc- 
ture of long integers called MATRIXLF and the default matrix with now 
operations performed can be represented as: 


#define UNITY 65536L \/ 
MATRIXLF mat[] = {UNITY, 0, 0, 0, UNITY, 0, 0, 0, 1}; GJ 


You can embed transform matrices within segments or you can call seg-\_) 
ments directly or from other segments using the call: 


Ww 

GpiCallSegmentMatrix(hPS, segnum, count, mat, options); &) 
where Ww 
segnum is the number of the unchained segment you want tow 
transform and draw. ‘oF 

count is the number of elements in the matrix (0-9) that are tow 


be used. Default values are used for any unspecified ele-__) 


ments. | 
ed 
mat is the transform matrix. > 
ae, 
options can be TRANSFORM_PREEMPT if this transform) 


supersedes the existing one on _ the segment, 
TRANSFORM_REPLACE if this transform should 
also. replace that one on the segment, and\/ 
TRANSFORM_ADD if this is in addition to the) 
existing transform. 


Seec¢ 
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Drawing and Transforming a Segment 


J 


A segment which is to be called and transformed, must be unchained, and 
' / the default is chained. Therefore you must modify the attribute of any such 
©) segments after they are created. The code below draws a simple line in a 


am Segment: 
) Gpi0penSegment(hPS, segnum); /*callable segment Fi 
GpiSetTag(hPS, segnum) ; /*tag with a segment number “/ 
-pt.x = 200; pt.y = 200; /*line origin ay 
©) GpiMove(hPS, &pt); 
pt.x = 400; pt.y = 100; /*line end ae 
“Gpiline(hPS, &pt); /*draw it a 
) GpiCloseSegment (hPS); 
am GpiSetSegmentAttrs(hPS, 
segnum, /*set to unchained a 
mo ATTR CHAINED, 
Fal ATTR_OFF ) ; 


) Then, you can draw the segment at PAINT time, once in its original position 
om and once translated by (50, 50) by defining a suitable transform matrix: 


m) #define UNITY 65536L 


abe 
“MATRIXLF mat[] = {UNITY, 0, 0, 0, UNITY, 0, 50, 50, 13; 
rie’ 


iam, GpiDrawSegment(hPS, segnum) ; /*“draw original */ 
GpiCallSegmentMatrix(hPS, segnum, 9, /*draw transformed*/ 

‘ak mat, TRANSFORM REPLACE) ; 

Oo, 

©) SUMMARY - USES OF SEGMENTS 

lan 


The entire segment structure is intended primarily for technical computer- 
aided drafting and design (CAD-CAM), where a segment is used to build 
‘al up a very complex structure from a series of elaborate floating point calcu- 
o» lations. The point is that in most scientific cases the segment overhead is no 
less than if you were to calculate the drawing coordinates and pick positions 
yourself from your knowledge of screen coordinates and the scale of your 
data on the screen. Thus, if you have only a few drawings or plots and a few 


m, 
co) 
) 
a) 
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places where you might wish to intercept a mouse click, you may not find 
the segment method any more advantageous than calculating the inter- 
section yourself. 
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18 Images and Bitmaps 


PS STIFF SSTSISISSTSISESGS 


Frequently, scientific data consist of a number of consecutive scans of a 
©) sample, either sweeping over it in successive lines or representing scans 
op» obtained during different sample perturbations. Examples include scanning 

electron microscopy (SEM), scanning tunnelling microscopy (STM), and 
two-dimensional nuclear magnetic resonance (2DNMR). Such scans can be 
> combined to form a raster image that can be displayed on a PM screen. 
™» Bitmaps can also be used to represent icons and other drawings. 
In PM, bitmaps can be 1, 4, 8, or 24 bits per pixel. In a 1-bit bitmap a 
pixel can only be “on” or “off,” while the 4- and 8-bit bitmaps can have 16 
©) or 256 shades or colors per pixel. The 24-bit bitmap assumes that each pixel 
), has a 24-bit RGB value, where 8 bits are used by each of the three primary 
- colors: red, green, and blue. 


on" 
@, DISPLAYING AN IMAGE 


) To display an image in PM, we need to 


oO 1. Create a memory Device Context. 

©) 2. Create a memory Presentation Space. 

™) 3. Create a memory bitmap. 

@, 4. Associate the bitmap with the memory PS. 
5. Create a color lookup table. 

©) 6. Determine the size of the image. 


o 255 


~*~ 
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7. Read the file into memory a line at a time. 

8. Set the bitmap from the file data. 

9. Determine the screen area to display the image in. 
10. Block transfer the bitmap to the screen area. 


The Memory Device Context and Presentation Space 


The memory device context is created using a DEVOPENSTRUC structure 
pointing to the DISPLAY.DLL device driver: 


DEVOPENSTRUC dop; 
hDCmem = DevOpenDC(hAB, OD MEMORY, ''*'', 8L, 
(PDEVOPENDATA)&dop, NULL); 


©0000 8008080800 8 0 


Then, we create a normal presentation space in memory with a size equal to\ 
the maximum possible screen size: 


Sz.cx = WinQuerySysValue(HWND DESKTOP, SV CXFULLSCREEN) ; 
sz.cy = WinQuerySysValue(HWND DESKTOP, SV_CYFULLSCREEN) ; 
hPSmem = GpiCreatePS(hAB, hDCmem, &sz, 

PU PELS | GPIT NORMAL | GPIA ASSOC); 


Seeede 


Creating a Bitmap 


We can then create a bitmap using the GpiCreateBitmap call where we tell 
OS/2 the size of the bitmap and the number of bits per pixel, by putting this 
information in a bitmap info structure. The pmgpi.h file defines a bitmap\y 
info structure and a bitmap info header structure, which are identical except 
for the color lookup table at the end. However, for 8-bit bitmaps, it does not. 
appear that storage for all 256 possible colors is correctly allocated. There- 
fore, we will create a structure with 256 RGB values already allocated: 


typedef struct { /*Bit map header structure definition’/ 
ULONG cbFix; /*“length of structure a 
USHORT cx, cy, /*size of bitmap ss 
cPlanes, /*number of planes oF 
cBitCount; /*bits per pixel ny 
RGB rgb[256]; /*look-up table ay 


3} BMAPHEADER; 
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©) The RGB structure we describe here is a 24-bit or 3-byte entry for each pos- 

@ sible intensity, where there is an 8-bit entry for each red, green, and blue 
color. It is important that you compile this module with the /Zp C-compiler 
option, so that all structures are packed on 8-bit boundaries. Otherwise, the 

) structure members will be aligned on word boundaries and won’t be accessed 

@) correctly by PM. We initialize the header part of the structure and create 
the bitmap as follows: 


/* Create space for a 100 x 100 bitmap */ 


O)/* with 8 bits per pixel os 
Py dail aden eee en RAE ny 
binf.cbFix = 12; /*length of header “*/ 
ry binf.cx = 100; f"x% size ae 
Mm  binf.cy = 100; /*y size a: 
binf.cPlanes = 1L; /*“only one plane a 
oO binf.cBitCount = 8L; /*8 bits per pixel / 
©) hBmap = GpiCreateBitmap(hPSmem, 
Ps Ebinf, /*“create the bitmap ~*/ 
OL, (PBYTE)NULL, 
oO (PB|TMAPINFO)NULL) ; 
a  GpiSetBitmap(hPSmem, hBmap) ; /*select the bitmap */ 
/* inte this PS 7 
o, 


The remaining parameters of the GpiCreateBitmap call have to do with ini- 
tializing special devices and loading the bitmap into device memory. For 
standard PM displays these are not used. 


a 


Initializing the Color Lookup Table 
a» 
Our bitmap consists of 8-bit numbers from 0 to 255 representing intensities 
of some measurement, or colors of an image. We can tell PM to render these 
colors as any RGB value it can select by loading the color lookup table with 
yan RGB value for each of the 256 intensities. In the simplest case we simply 
ayxmake these 256 shades of gray: 


AAAS. 
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for (i=0; 1<256; i++) 


begin 

binf.rgb[i]. So saelaae 
binf.rgb[i].bRed=(BYTE) i 
binf.rgb[i].bGreen= (BYTE) | 
end 


where the red, green, and blue values increase at the same rate from 0 to 
250: 
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READING AN IMAGE FILE INTO A BITMAP 


One common image file format contains no header information and has 8 

bits per pixel of data. When data are in this format, we need to know the 
number of rows and columns in the file, since there is nothing in the file” 
itself to tell us. In the example below, we read in a row of data at a time into’ 


Ww 
a memory and use the call GpiSetBitmapBits to set the values in the oa 
bitmap. This call has the form 
WY 
GpiSetBitmapBits(hPSmem, linenum, lines, 
bptr, (PBITMAPINFO)&binf); Y 
where pad 
, WY 
hPSmem is the handle to the memory PS we created. | 
YY 
linenum is the line number where we will begin the data transfer. UL 
line is the number of lines of data to transfer to the bitmap. wy 
bptr is a pointer to the buffer where those data lines aré_) | 
stored. 6) 
WY 
& binf is the pointer to the bitmap info structure describing the_) 


bitmap format. 


In this example, we read the entire bitmap into memory so we can alsq 
manipulate it later, but we only need to read in a line at a time as we ar 
only changing a line after it is read in. 
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M)bptr = malloc(binf.cx * binf.cy); /*allocate data space*/ 
a fptr = fopen(pim->filename, ''rb'');  /*open the file a i 
‘for (i=0; i<binf cy; i++) /*read a line at a time*/ 

o begin 

> fread(bptr, binf.cx, 1, fptr);: /*read a line x f 
GpiSetBitmapBits(hPSmem, i, 1,  /*set the bitmap */ 

Om bptr, (PBITMAPINFO)&binf); 

™ bptr += binf.cx; /*advance the pointer*/ 
end 

Fclose (fptr); /*close the file when done*/ 

> 

ao 

le THE BITMAP ON THE SCREEN 


om Now that we have loaded the bitmap with values, we need only transfer it 
from the memory bitmap to the actual screen using a bit-block transfer or 
BitBlt function. The GpiBitBlt call also will scale the memory bitmap to a 

larger or smaller screen bitmap automatically. The call has the form: 


epipiteit(hps, hPSmem, count, dims, rop, options); 


oo 
where 
om 
~~ is the destination bitmap, usually the screen. 
oy hPSmem is the source bitmap, usually a memory bitmap. 
count is the number of point pairs from the dims array to inter- 


pret. If it is 3, the destination rectangle is the same size 
as the source rectangle. If it is 4, stretching or com- 
pression is performed on the destination bitmap rec- 
tangle. 


= 
5 
7) 


is an array of 4 POINTL structures, in the order 
DestBottom, DestTop, SourceBottom, SourceTop, where 
the destination bottom left corner and upper right corner 
are specified in the first two structures and the source 
bottom left and upper right corners are specified in the 
second two structures. These define the sizes of the desti- 
nation and source rectangles. 
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WY 
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rop is one of several logical raster operations that can be per-(_ > 
formed in mixing the source rectangle into the destina- 
tion rectangle. The more common ones are 
ROP_SRCCOPY, ROP_SRCINVERT, 
ROP_SRCPAINT, and ROP_SRCAND which replace,_) 
XOR, OR, or AND the source with the destination 
bitmap. Y 


, 
options is BBO_OR, BBO_AND, or BBO_IGNORE, describing 
how to merge any eliminated columns if the destination 
is smaller than the source. For color bitmaps, 
BBO_IGNORE is the preferred method. &) 
In the complete paint procedure, we get the current window size, set it into _) 


the dims array and bit-blit the bitmap onto the screen: ram 
O 


case WM PAINT: 

WinQueryWindowRect(hWnd, &rc); /*get window dimensions”*/ 
dims[O].x = 0; /*“destination dimensions*/ 
dims[O].y = 0; LU 
dims[1].x = rce.xRight; 
dims[1].y = rc.yTop; nd 
dims[2].x = 0; /*source dimensions “| @ 
dims[2].y tie 
dims[3|.*x = binf.cx; Y 
dims[3].y = binf.cy; a, 
GpiSetBitmap(hPSmem, hBmap) ; /*select bitmap as | & 
GpiBitBIt(hPS, hPSmem, 4, p, 

ROP SRCCOPY, BBO IGNORE); WY 
GpiSetBitmap(hPSmem, NULL); /*deselect bitmap a | aP, 
WinQueryUpdateRect(hWnd, &rc); & 


WinValidateRect(hWnd, &rc, 
TRUE); /*validate entire region*/ (y 
break; 
wy 
&Y 
THE COLOR LOOKUP TABLE & 


While we can put any set of RGB values we like into the lookup table, the 
display and device driver may limit your choices to ones that it can actuall}_ 
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produce on the screen. For example, on an EGA or VGA screen, there can 
only be 16 colors out of a possible 64 at a time, and these are selected by the 
device driver to be compatible with the historical PC’s CGA colors. On the 
514 display (BGA) there are 256 colors selectable out of a possible 256,000 
Mysolors, but the selection has been made in the device driver and these colors 
ancannot be changed since they would change the colors in other screen 
windows as well as the one you are currently working in. Instead, PM uses 
Orne closest existing color to the color you requested. This often results in 
many fewer colors than you may have requested. 


oo 
Realizing a New Lookup Table 


The Gpi calls allow you to create and load new logical color tables, using 
RGB values to describe the colors you wish to use. However, in OS/2 1.1 
yone of the display device drivers yet support these calls because of the pos- 
sible conflict between colors when multiple windows are on the screen. The 
calls are as follows: 


om 


mGpiCreateLogColorTable(hPS, options, format, start, 


count, table); 
om 


amGpiRealizeColorTable(hPS) ; 


where 

Onps is the presentation space handle. 

@ ptions iS LCOL_RESET, LCOL_REALIZABLE, — or 

o- LCOL_PURECOLOR, to reset to the standard color 

ma table, realize the current one, and prevent color dithering 
for colors that are not available. 

o 

format is LCOLF_INDRGB, LCOLF_CONSECRGB, © or 
LCOLF_RGB. The first format is a long index value 

Oo followed by a 32-bit RGB value, the second is a list of 

eo 32-bit RGB values, and the third is an array of 24-bit 

a RGB values. 

start is the index of the first value to be replaced. 


»@@@ 
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count is the length of the table. 


table is the RGB color lookup table in one of the formatl_) 
described above. If LCOLF_RGB is selected, the entir® 
table must be replaced. 


The create call loads the table into that presentation space and the realize 
call loads the table into the devices hardware lookup table. 


CHANGING LOOKUP TABLES 


© @ @< 


If you attempt to display an image on an EGA or VGA display as a series 0_) 
grayscale tones, you will find that only four shades are displayed: black 
dark gray, light gray and white, even though you specified 256 different 
gray levels in your RGB lookup table. This is clearly unsatisfactory and you’ 
must therefore change the lookup table to use more colors to distinguish tht_» 
various intensity levels in your image. Since we know which RGB levels ar¢ 
actually used in the display, it is fairly simple to construct a new lookup 
table and reload the bitmap. In the example below, we create an 8-colom 


lookup table: 

/* sah ac ste cms 0 pes fo acces du eal pa came pnts cen AS Ve tees el el dani a as eras eae dec oe Osa de / 
/* reload the color lookup table with 8 primary colors */ 
din tatainientatatatatataiatabatainatatatarataiaienaanaminianta naar aan / 


void colorlut(UCHAR “image, int “bins, BMAPHEADER “binf, 
HPS hPSmem, HBITMAP hBmap) 


begin 
long 13 
UCHAR lut[256], “bptr; 
int err; 
GpiSetBitmap(hPSmem, hBmap) ; /*select bitmap*/ 
for (i=0; i<32; i++) pla / 
binf->rgb[i].bBlue= 0; 
binf->rgb[i].bRed= 0; 
binf->rgb[i].bGreen= 0; 
for (i=32; i<64; i++) /*blue*/ 
binf->rgb[i].bBlue= Oxff; 
binf->rgb[ i].bRed= 0; 
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binf->rgb[i|.bGreen= 
for (i=64; i<96; i++) 
binf-?rgb[t|.bBlue= 
binf<-rgb| i ].bRed= 
binf->rgb[i].bGreen= 
for (i=96; 1<128; i++) 
A>, binf=*rgb[ 1 |.bBlue= 
binf->rgb[i].bRed= 
oO binf->rgb[i].bGreen= 
M) for (i=128; i<160; i++) 
bint->rgb[1].bB lue= 
binf->rgb[ i].bRed= 
©) binf->rgb[i].bGreen= 
| @for (i=160; i<192; i++) 
binf->rgb[i].bBlue= 
o binf->rgb[i].bRed= 
My  binf->rgb[i].bGreen= 
for (i=192; i<224; i++) 
bint-2rgqb/ t).o68.)ve= 
| @& ~~ sibinf->rgb[i].bRed= 
o> miner aRL te Oeree a 
for (i=224; i<256; i++) 
©) © binf->rgb[i].bBlue= 
o~ 


}0@000@ 


binf->rgb[i].bRed= 
binf->rgb[ i ].bGreen= 


a@mptr = image; 
tor (i=0; i < binf->cy; 
begin 


i++) 


MO err=GpiSetBitmapBits(hPSmem, 


o 


| or 
> bptr += binf->cx; 
end 


a 
aand 


}d9ee090 


1, 


bptr, 
(PBITMAPINFO)binf); 
/*“advance the pointer 
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/*green*/ 


fPevan’/ 


/*red*/ 


/*magenta™/ 


/*yellow™/ 


/*white*/ 
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“pointer to start of image”*/ 


/*read a line at a time*/ 


/*set the bitmap 


sl 
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PLOTTING AN INTENSITY HISTOGRAM & 


It is often instructive to view a histogram of the intensities in an 8-bit image— 
so that you can decide how contrast might best be enhanced. It is obviousl\ 


not difficult to make a 256-word array and count the number of pixels thal ) 


have each of these 256 values: 
tL. ! U Y 
kmax = cx “ cy; /“total image size ar 
for (i=0; i<256; i++) /*“zero out the array *y 
begin YW 
bins[i] = 0; LY 
end 
for (k =0; k< kmax; k++)  /*for each byte * (ZO 
begin 
bins[ image[k ] ]++; /*“increment that intensity bin*/ 
end 


Then, you can open a child window and plot these intensities as a series of 
vertical lines at each of 256 horizontal positions: WY 


WinFillRect(hPS, &rc,CLR BLACK); /*fill it with black */~— 


GpiSetColor(hPS, CLR WHITE); /*set color to white */©U) 
bin = (int *)WinQueryWindowULong(hWnd, 0); 
max = 0; 
for (i=0; i<256; i++) 
begin 
if (bin[i] > max) then /*find maximum count */ 
max = bin[i]; 
end 





scale = (float)rc.yTop / (float)max; /*get scaling factor*/ 
for (i=0; i<256; i++) 
begin 
pt.x = i; pt.y = 0; /*draw each line from the bottom*/ 
GpiMove(hPS, &pt); 
pt.y = (int)((float)bin[i]*scale); 
GpiLine(hPS,&pt) ; /*to its intensity value*/ 
end 


An image and a window containing the histogram are shown in Figure 18- 
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igure 18-1. An image from scanning tunnelling microscope data. The associated 
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histogram is shown on the right. 


) 


HISTOGRAM EQUALIZATION 


Once you have examined the histogram of intensities, it often improves the 
amimage significantly to spread out the counts over the entire range of intensi- 
ties, so that the number of counts in each of the intensity bins is more or less 
equal. This process is known as histogram equalization, and the result is 
hat the fraction of pixels below any given grayscale value is roughly equal 
emo the fraction of grayscale below this value. In this procedure, the lookup 
table remains the same, but once the histogram is calculated, the image is 
changed, byte by byte, so that each new value corresponds to a position in a 
\niformly distributed histogram. 


f si 
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ox" Histogram equalization routine af | 
a he a Nes see ache ag a aa Ng a gee et ae Be x / 


oid equalize(UCHAR “image, int “bins, BMAPHEADER “binf, 
om HPS hPSmem, HBITMAP hBmap) 


beg in 


long 1; 


»o@e@ 


266 IMAGES AND BITMAPS 


long sum, total; 
UCHAR lut[256], “bptr; 
int err; 


YO 
Ly 
YO 
oe 
OY 
Y 


total = 0; /*initialize running sums*/ Y 


sum=0 ; 
GpiSetBitmap(hPSmem, hBmap) ; /*select bitmap 
for (i=0; i<256; i++) 


wt 
7 


™~ 


begin 
total += bins[i]; /*calc total sum of intens*/ @) 
end 
for (i=0; i<256; i++) 
begin 
sum += bins[i ]; /*calculate running sum 


x sk 
Pay “y 
~ ~~ 


tn attitude theta tended athactotind 


/*set lookup table value 
lut{ i] = (UCHAR)(256.0%(float)sum/(float) total); 
end 


for (i=0; i< binf->cx * binf->cy; i++) 


image[i] = lut[image[i]]; /*set new intensities ay 
/* from lookup table a i 
bptr = image; 
for (i=0; i < binf->cy; i++) /*read a line at a time “*/ 
begin 
GpiSetBitmapBits(hPSmem, i, /*set the bitmap at | 
le BRL s 
(PBITMAPINFO)binf); 
bptr += binf->cx; /*“advance the pointer | 
end 
end 


The equalized image and its histogram are shown in Figure 18-2. 
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Histogram 


Figure 18-2. The same image as shown in Figure 18-1 after histogram equalization. 
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n Chapter 3, we looked at a simple program that started two threads of 
execution that ran simultaneously. We now will look at these features in 
apore detail as used in Presentation Manager programs. 


o™~ 
ot HE MESSAGE QUEUE AND TASKS 


Ane of the standard rules you should follow in PM programming is the 
\1-second rule: no message should cause processing that lasts longer than 
about 0.1 second. The reason for this is that such programs will not respond 
Lo user commands during that processing period and the program will seem 
») be locked up. In fact, not only that program, but all windowed programs 
ill be locked up during that processing time. If OS/2 is a multitasking 
coystem why is this so? This is not a consequence of the multitasking design, 
ut of the messaging system that windows use to process commands. Each 
vrogram has a message queue associated with its main window. Recall that 
ye main loop of the main routine of any PM program has the form: 


@hiiec ( WinGetMsg( hAB, (PQMSG)&qmsg, (HWND)NULL, 0,0) ) 


OY begin 
WinDispatchMsg(hAB, (PQMSG)&qmsq) ; 
end 


. 
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Because of this structure, no new messages can be processed until the pre 
vious one has been processed and returns from the dispatch message call. Ip 
addition, input messages from the keyboard and mouse are serialized. This 
means that keyboard and mouse messages must be processed in the orde/ 
they are received or their results could be meaningless. Therefore, if Ly 
message is received that causes a 30-second computation, no more messages 
will be processed until the program returns from that message. If you try to” 
switch to a window of some other program, it will not respond either: firs 
because the orginal program can’t lose the input focus without receiving VY 
deactivate message and second because input from the user is serialized an¢ 
no other window can receive messages until the end of the message proc- | 
essing taking place. Ww 
This can make a poorly designed program very sluggish and can make a\_, 
the running programs equally sluggish if your program disobeys thy 
0.1-second rule. Obviously, however, there must be ways of carrying on long | 
computations without locking up the system, and these are multi-thread pro’ 
gramming techniques. There are several possible scenarios where a long ca\__ 
culation is processed in an OS/2 PM environment. \) 


1. A thread carries out a computation and returns a result. oe 


2. A thread prepares a data table to be displayed rapidly when the calchv 
lation is completed. 


WY 
3. A thread performs a slow drawing task in the main window. VW 
4. A thread draws into a separate window. Ww 

WY 


5. A thread starts an entirely separate program. 


Each of these is possible in OS/2 PM and each is handled slightly differ 


ently. 


THE MULTITHREAD LIBRARY 


©O6O¢ 


The IBM C/2 and Microsoft C compilers provide a special version of the ( ) 
function library LLIBCMT.LIB, which contains the C functions in reen-. 
trant form. This allows several C threads to be making calls to the sane” 
function at the same time without any conflict. Because the reentrant funt_) 


@ < 


o« 
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f 


J 


ons must be called using the Pascal calling convention, the include files (.h 
iles) for the reentrant libraries have different declarations. For example, the 
definition of the cos function in the standard library include files is 


afouble CDECL cos (double); 
cwyhile in the multi-thread libraries it 1s: 
@ouble far pascal cos(double); 


Yo make sure that the correct calling convention is generated when the func- 

qions are called, you must be sure to use the multithread include files in the 
tNCLUDE\MT subdirectory. You can cause this to occur by specifically 
-hanging the #include declarations in your program to 


Oo 
oo 


r you can change the environment variable INCLUDE that is set in the 


CONFIG.SYS file or startup file to 
cy 


if 


#include <mt\math.h> 


SET INCLUDE=c: INCLUDE\MT;c:\INCLUDE; , 


Since nearly all significant OS/2 programs will in fact have multiple 
chreads, it is probably better to change the environment SET statement as 
Mhown above. This is what we have assumed throughout this text. 


a 


ROPERTIES OF WINDOWS IN THREADS 

aN 

eX ou can create a window in a thread, but that thread must then have its own 
message queue. If you create a thread that only performs computations and 

\ oes no displaying, no message queue is necessary. Only the thread that 

(Yeates a window can receive input for that window. A thread can draw into 

lan window created by another window, however, but such a thread must have 
ts own anchor block. Finally, a thread can post messages to a window in 

nother thread, but cannot send messages to another thread. 
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USING A SEPARATE THREAD TO DRAW IN THE 
MAIN WINDOW 


SOOeede 


In this example, THREAD1, we will create a 4096-point array of random 
numbers and draw lines between all of them on the screen. On mos_) 
machines this will take 4-5 seconds: much longer than the recommended 0.,/ 
to 0.5 seconds. We create the array as a global array for simplicity at the 


. ‘ . j 
same time we create the main window: 


#include <process.h>  /*where the thread definitions po 
VY 
/*register the Window class*/ > 
WinRegisterClass (hAB, /*“handle to anchor block af 
''Mainthread'', /*“name of window class «(WZ 
Hel loWndProc, /*“address of window procedure™/(__ 
CS SIZEREDRAW | 
CS_SYNCPAINT, /*use these flags a 
an ae /*“number of ''extra bytes “/@ 
for (i=0; i<XDIM; i++)  /*generate the array to display” 7 heed 
x[i] = (int) ((float)rand()*200/32768.0); WL 
flCreate = = 
FCF TITLEBAR | FCF MINMAX |FCF_ SYSMENU | YW 
FCF MENU | FCF SIZEBORDER | FCF BORDER | ‘o, 
FCF SHELLPOSITION | FCF ICON; 
Cy) 
/*create the window */ , 
hFrame = 
WinCreateStdWindow( Y 
HWND DESKTOP, /*child of the desktop window*/\) 
WS VISIBLE | FS ICON, & 
&f1Create, /*control data bits ae 
''Mainthread', /*this name refers to class *“/NY 
‘Hello World’, /*title across top bar “/@ 
wS VISIBLE, /*main window visible a 
NULL, /*menu is in resource file *“/\/ 
HELLOICON, /*frame window id-you pick */C >} 
&hWnd) ; /*client area handle n 
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“The Main Window Procedure 


{he main window procedure is much like that of previous simple program 

-xamples, except that the command DRAWIT ts used to create a stack for 
he thread and start it. A minimum stack size for a new thread is 2000 
mytes: threads which use a lot of array space will require larger stacks, since 

ocal variable space as well as intermediate computation storage is allocated 

_com that stack. Note that the argument we pass to the thread is the main 
)indow handle. 


RESULT FAR PASCAL HelloWndProc(HWND hWnd, USHORT msg, 


om MPARAM mp1, MPARAM mp2) 
akegin 
HPS hPS; /“handle to presentation space “*/ 
O) RECTL re: /*“rectangle definition structure*/ 
@ char ‘stack: /*pointer to stack space 7 
Owitch (msg) /*interpret messages a 
apegin 
Arse WM COMMAND: /*“interpret commands se 
)  switch(LOUSHORT(mp1) ) 
> begin 
| case DRAWIT: /*call thread to draw in window*/ 
om stack = malloc(2000); /*get stack space mf 
~ _beginthread(Drawthread, | | 
stack, 2000, hWnd); /*start the thread*/ 
oo break; 
default: /“else do nothing a4 
- return(WinDefWindowProc(hWnd, msg, mpl, mp2)); 
on end 
WinlnvalidateRect(hWnd, NULL, FALSE); /*“force repaint */ 
@ break: 
o™, 


ames WM PAINT: 
~ APS = WinBeginPaint(hWnd, 
(HPS)NULL, (PWRECT)NULL); 
los /*get current window dimensions 
WinQueryWindowRect(hWnd, &rc); 


J 
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WinFillRect(hPS, &rc,CLR BLACK); /*fill it with black */@ 
WinEndPaint(hPS) ; /*end painting Koueiier ne 
break; | 
default: /*“pass on other messages” 
return( WinDefWindowProc( hWnd, msg, mpl, mp2)); 
break; 


end /*switch*/ 


return(OL); 
end 
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The Drawing Thread 


In the drawing thread, we will get a presentation space and draw into eS 
The most important single thing a drawing thread must do is allocate i__ 
own anchor block: a thread without one will fail miserably. As before, w 
calculate the window size so we can scale the drawing appropriately an 
then begin the drawing process. When the drawing is completed, the PS ad 
released, the anchor block terminated, and the thread ends on exiting th_) 


function. &) 
void Drawthread(HWND hWndParent ) oe 

/* independent thread for drawing the x array into sf 
/* the specifed window’/ oT hel 
begin a, 
long xpos, xXinc; ia 
HPS hPS; /“local presentation space a [SO 
RECTL. re; /*“rectangle for window size *KO 
POINTL pt; /*“location for each move and draw"/_) 

int 1 ,errs 

HAB hABtask; /*local anchor block * av 
Ww 
hBABtask = | a 
Winlnitialize (NULL); /“init and get anchor handle" 
hPS = WinGetPS(hWndParent); /*get a cache micro PS “KJ 


GpiSetColor(hPS, CLR BLUE); /*set line color to blue “*/ 
/*get current window dimensions a 
WinQueryWindowRect(hWndParent, &rc); 


WwW 
7, 


ww 
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OL; 
xinc = /*compute x increment i 
(long) ((float)(rce.xRight * 65536L)) / (float) XDIM; 
A™t.x = 0; 


t.y = x[ Ol; 
apiMove(hPS, &pt); /*‘move to first point a 
pos += xinc; /*increment x * / 
ghor (i = 1; i < XDIM; i++) /*“draw remaining points * 
— begin 
a, pt.x = (int)(xpos >> 16); /*calculate new x position */ 
am pty = x[i]s /*get new y posn from array*/ 
GpiLine(hPS, &épt); /*draw next line a 
oO xpos t= xinc; /*increment x */ 
Om, end 
inReleasePS(hPS) ; /*release cached PS * | 
«inTerminate(hABtask) ; /“end this thread xy 
Mynd 
a» 


CSOMPUTING A DISPLAY BUFFER IN A SECOND 
HREAD 


.,nother common use for a second thread in producing a display is to calcu- 
te the contents of a display buffer that can be displayed rapidly with a 
cpiPolyLine call in the main thread. While the calculation is taking place, 

e main thread remains active to mouse and keyboard messages and can 
process other menu items, but the main display will appear after a short cal- 
O "Nation interval. 
™) In the example below, we create a window and as soon as its size is 
ehown it creates a thread to fill up a display buffer. As soon as the buffer is 
uilled, the thread posts a DRAWREADY message to the main thread and 
‘Jen terminates. As before, for simplicity we will keep both the original x 
ta as a global array and the buffer of POINTL variables and bufmax as 
anell. 
When our main window first starts up, it will receive a WM_PAINT 

_.essage. However, our buffer will not be ready yet, so we initialize the first 
©yation of the display buffer to 10000 and skip any calls to the GpiPolyLine 
@~nction until the buffer has been filled. When the DRAWREADY message 
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is received, it invalidates the entire window, forcing a new WM_PAIN 
message, which will this time display the data. 


aL 
wv 


S8egoeces 


/* main window procedure for THREAD2 - 

/* buffer is filled in second thread 

MRESULT FAR PASCAL MainWndProc(HWND hWnd, USHORT msg, 
MPARAM mp1, MPARAM mp2) LY 


SL 
wv 


TN 


begin oO 
HPS hPS; /“handle to presentation space ‘/© 
RECTL re: /*rectangle definition structure*/ 
char “stack; /*“pointer to stack space * f 

) 
switch (msg) /*“interpret messages “| /~ 

begin Y 

? 
case WM SIZE: Y) 
/*get current window dimensions my 
WinQueryWindowRect (hWnd, érc); Ww 
buffer[0].x = 10000L; /*use as flag for completion’ JO 
stack = malloc(2000) ; /*get stack space 
_beginthread(Fillthread, /*start drawing thread /@ 
stack, 2000, hWnd); VW 
break; s 
case DRAWREADY: ‘oe 
WinlnvalidateRect (hWnd, & 
NULL, TRUE); /“force paint message ay 
break; WY 
Y 
case WM PAINT: | 
hPS = WinBeginPaint(hWnd, (HPS)NULL, (PWRECT)NULL); 
/*get current window dimensions ‘/ 
WinQueryWindowRect(hWnd, &rc); 
WinFillRect(hPS, érc, CLR BLACK);/*fill it with black* 
GpiSetColor(hPS, CLR WHITE); /*draw white lines “(QD 


if (buffer[0].x != 10000L) then /*only if the buffer*/ 
/*is now filled 
GpiPolyLine(hPS, bufmax, buffer); 
WinEndPaint(hPS) ; /*“end painting routine” 
break; 


ccccce’ 


f 


a 

o 
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om 

a 

™) default: /*pass on other messages*/ 


return( WinDefWindowProc( hWnd, msg, 
mp1, mp2)); 


} 


on break; 


en /*switch*/ 


Oyeturn(OL); 
aend 


@™) Our second thread procedure Fillthread now needs no message queue or 

anchor block, because it is processing no messages or doing any drawing. 
After it has filled the buffer, it posts a message to the main window proce- 
Oure in the first thread, which causes the screen to be painted: 


LER eee ON erry ere ' 
OY* independent thread for drawing the x array into the ~*/ 
Med aie ala Sea ih cedeat at Bins ea iarca iierriginalns tse atu eee eared 7 


oid Fillthread(HWND hWnd) 


anbegin 


long xpos, xinc; 


= int err, i, j, min, max, Oldmin, oldmax, xp; 
mm, float leftpnt., rightpnt, pts per bing 
REGTL re; 

io BOOL up; 
Oo t 

/“get current window dimensions a 
~ WinQueryWindowRect (hWnd, &rc); 
O»ts per bin = (float)XDIM/(float)rc.xRight; 

Be 

/* £111 the buffer with mins and maxes * f 
Oeftpnt = U,05 
ae idmin = 0; /*initialize maxes and mins*/ 

oldmax = 0; 

ip = TRUE; /*“and up flag “7 
amp =0; 

rightpnt = pts per bin; /*size of one bin a 
@hite(rightpnt < XDIM) 
OY begin 


a min = 10000; 
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max = ~10000; /*find max and min in each group */ 
for (i = (int)leftpnt; i < (int)rightpnt; i++) 
begin 
if (max < x[i]) then max = x[i]; /*“look for new max */ 
if (min > x[i]) then min = x[i]; /“and new min mf 
end 


if (min > oldmax) then 
min = oldmax; /*check for overlap with last line*/ 
if (max < oldmin) then 
max = oldmin; 
oldmax = max; 


SSOSOSOOOHHOOOHOOOOOOOCOS SE 


oldmin = min; /*save for next pass 
if (up) then 
begin 
puTTer| jj.x = xp} 
buffer[ j++].y = min; /*put min and max in buffer */ 
puT rer jf |s* = xp 
buffer[ jt+].y = max; 
up = FALSE; /*next one will draw down oe 
end 
else 
begin 
buffer| j|.x = xp; 
buffer[ j++].y = max;  /*put min and max in buffer “*/ 
puffer| [jx = xprr; 
burfer| [tt] .y = mins 
up = TRUE; /*“next one will draw up sf 
end 
leftpnt += pts per bin; /*go on to next grp of points*/ WY 
rightpnt. += pts. per bin; Vv 
end : 
bufmax = j - 1; /*remember how big the buffer is 7 need 
err= /*tell other thread ready to draw*/ (> 
WinPostMsg(hWnd, DRAWREADY, OL, OL); 
end Y 
~ 
CREATING A WINDOW IN A SECOND THREAD = 
Cy 


Another possibility at first might seem to be the creation of a complet(_) 
window for drawing in another thread. It is perfectly possible to create suck 
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™)a window, but again, it too must obey the 0.1-second rule and not take long 
™» periods of time to process messages. 
af you create a window in another thread, it must have both its own 
‘message queue and anchor block. In the example below, the following code 
Mis executed when the second thread is started to create the second window: 


@voia Drawthread(HWND hWndParent) 


@)/* opens a window in this thread */ 
ao labs ot : 
QMSG qmsg; /“defining a message queue”/ 
Oo HAB hABtask; 
ULONG f1Create; /“window create flag bits “/ 
©) HWND hFrame, hWnd; 


/*init and get anchor handle *Y 
hABtask = WinInitialize (NULL); 

mhmdChild = 
-~WinCreateMsgQueue(hABtask, 0); /*create msg queue #Y 


\/f1Create = FCF_TITLEBAR | FCF_MINMAX |FCF SYSMENU | 


io FCF SIZEBORDER | FCF BORDER IFCF SHELLPOSITION ; 
a/ “create the window */ 
hFrame = WinCreateStdWindow( 

on hWndParent, _ /*as child of calling window*/ 

o NULL, /*not yet visible a 
&f1Create, /*control data bits my 

= "Child, /*this name refers to class “/ 

a> Child Window’, /*title across top bar i 
wS VISIBLE, /*child window visible a 

> NULL, /*no menu oy 

o 25 /*frame window id-you pick */ 

> &hWnd) ; /*client area handle Fi 


MyY*now show the window 100 x 100 

caw inSetWindowPos(hFrame, HWND TOP, 

100, 100, 100, 100, 

SWP SIZE | SWP MOVE | 

SWP_ SHOW | SWP ACTIVATE); 


—, 


»@ 


while ( WinGetMsg( hABtask, &qmsg, (HWND)NULL, 0, 0) ) 
begin 
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WinDispatchMsg(hABtask, &qmsq); 


end 
/*once the program is over, */ 
/* destroy the window and message queue * 
WinDestroyWindow(hFrame) ; /*destroy the window “*/ 
WinDestroyMsgQueue(hmqChi 1d) ; /*“and the message queue”/ 
WinTerminate (hABtask) ; /* and the anchor block*/ 
end 


STARTING A SEPARATE PROCESS 
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You can also start up completely separate programs from your program(_) 
Each is termed a “child process” but executes independently from your 
program and can continue even if your program terminates. You start sepa- 


rate programs using the DosExecPgm call WY 
err = DosExecPgm(objname, objlen, flags, Y 
argptr, envptr, &rcode, progname) ; WwW 
where WY 
objname is a String where the name of the object that caused thew 
failure of this call is returned. , 
objlen is the length of this buffer. WY 
flags contains information regarding how the program 1s to bw 
executed: a, 
0 Program executes synchronously. VY 
1 Program executes asynchronously and its resul(_) 
code is discarded. & 

2 Program executes asynchronously and its result 
code is stored in the first word of the reode struc— 
ture. a, 

3 Like value 2, except the program executes unde; 


conditions for debugging. 
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4 The program executes in the background as a 
detached process. It should not require any input 
or output. 

5 The program is loaded but not executed until the 


session manager starts the threads belonging to 
the process. 

6 The program and its descendants execute under 
conditions for debugging. 


73000000009 


argptr is a pointer to block of argument strings passed to the 
a 
UD program. These are discussed below. 
y 

envptr is a pointer to a block of text strings like the SET envi- 
am 

| ronment variable strings. 
en 

rcode is a pointer to a RESULTCODES structure shown 
cc below. 
© progname is the name of the file to be executed. This name must 
eon include the extension and may include a path name. 
err is zero if no error occurred. 


Oirhe RESULTCODES sttucture has the form 


on 
typedef struct RESULTCODES { 
) USHORT codeTerminate; /*Termination Code or Process |D*/ 


USHORT codeResult; /* Exit Code oF 
3} RESULTCODES; 


The Argument String 


«The convention in both DOS and OS/2 is that the string argptr passed to 

anmthis function contains as its first component the program name, then a null 
byte, then the arguments, and then two null bytes. Thus, if you wanted to 
execute the command 


c:\adc\acquire.exe data.txt 


ou would create a name string as follows: 
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VY 
char name[80], “s, ob jbuf[80]; C) 
RESULTCODE rcode; 

& 
strcpy(name, path); /eontaing “ep\ade\” a LU 
strcat(name, ‘'Acquire.exe'): /“add the program name “*/ 

S = name + strlen(name) +1; /*“point beyond null byte */ Y 
strcepy(s,  data.txt }: /*“add argument string a 7, 
DosExecPgm(ob jbuf, 80, 1, name, Y 

NULL, &rcode, name); /*asychronous start */ @ 


Once you have another program running, you can communicate with it’ 
through semaphores, pipes, queues, or shared memory as described in th«_) 
following chapter. 
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Threads 
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Osince OS/2 is a multitasking system, it 1s often necessary to have one 

process or thread wait until a task being performed by another thread has 

completed. There are three ways of communicating between processes and 
threads: semaphores, pipes, and queues. In addition, as we have seen earlier, 
cimers can be used to trigger processing after a specified interval. 


om, 


SEMAPHORES 
o~ 


MA semaphore is a flag that can be either | or 0 and can be tested and set by 
one or more entities. There are two kinds of semaphores: system semaphores 
and RAM semaphores. System semaphores have names like filenames and 

Mnaintain a use count so they can be accessed by recursive routines. RAM 

«semaphores are just double words of storage within a program that have no 

ownership or use count and cannot be accessed recursively. A special fast- 
safe RAM semaphore structure can also be created so that ownership can be 
cracked. 

m, 

io 
SYSTEM SEMAPHORES 

a, 


com system semaphore is a named resource like a file, and always has the 
“subdirectory” \SEM\. You create a system semaphore with 
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DosCreateSem(noexcl, &hSem, name); 


©@000¢ 


where 

noexcl is a flag indicating whether the creating process wants) 
exclusive ownership of the semaphore. If it is 0 the cre-y~ 

ating process has exclusive ownership, and if it is 1 then 
other processes can modify it. Y 
& hSem is the address where the handle to the semaphore i 
returned. YO 
name is the semaphore’s name. It must have the prefix or 
“subdirectory” of \SEM\. a, 
Once you have created a semaphore, you can use the following calls tow 
clear, set, and test it: —, 
DosSemC lear (hSem) ; /* clear a semaphore */ @ 
DosSemSet (hSem) ; /* set a semaphore a YY 

DosSemWait(hSem, timeout); /* block thread . 
/* until semaphore clears “*/ VY 
DosSemSetWait(hSem, timeout); /* block thread until sem */ i, 
/* €lears, then set it nee | 
DosSemRequest(hSem, timeout); /* block thread until ar | Y 
/* ownership available */ @ 

DosMuxSemWait(&index, : 
WwW 


list, timeout); /* block until one of sems “*/ 


/* in list clears IO 

In all cases timeout is the number of milliseconds to wait. If it is -1, the wait 
is indefinite. VC 
LF 


Semaphore Ownership wy 


A semaphore is owned by the thread that sets it. If the semaphore is created 
as exclusive (noexcl flag set to 0) then no other process can set or clear it. 
Thus, the DosSemRequest blocks the current thread until it can set av 
semaphore or, in other words, until it has been cleared by another thread. By 
contrast, the DosSemSetWait call does not establish semaphore ownership, 
since it waits until the semaphore can be set, but does not set it. 
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The following example creates a semaphore, sets it, and waits for it to be 
@) cleared by a second thread. The second thread simply issues a DosSleep for 
2 seconds and then clears the semaphore. Note that the system semaphore 


) 


“name string includes double backslashes, since backslashes themselves indi- 
) cate that a special character follows in C strings. 


@ /‘simple program to set and wait for a semaphore to clear”/ 
void main() 
am begin . 
unsigned char “stack; 
- HSEM hSem ; 


‘DosCreateSem(1, &hSem, 
'\\SEM\\TIMER.TIM'');  /*create a system semaphore*/ 


@p DosSemSet (hSem) ; /*set the semaphore high “*/ 
OM /*create a semaphore clearing thread */ 
@) stack = malloc(2000); /*get stack space sf 
_beginthread(SemCIr, stack, 
‘*, 2000, &hSem) ; /*“pass address of semaphore*/ 
™) DosSemRequest(hSem, -1L); /*block thread * 
/*“until we can set sem a | 
printf( Exiting \n ); /*“exit message x / 
O)DosExit(1, 0); /*end all threads Fi 
mend 
i rrr cscccce / 
O/* waits 2 seconds and clears sem </ 
aa aa ai ea ri el / 
void SemCIr( HSEM “hSem) 
“begin 
(M)DosSleep(2000L) ; /*wait 2 seconds ai 
any DOSSemC lear (“hSem) ; /*and clear the semaphore “*/ 
end 
om, 


O sharing Semaphores between Processes 


om If you want to access a system semaphore in a totally separate program or 
process, you will have to open the semaphore and obtain its handle using the 
DosOpenSem call 
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DosOpenSem(&hSem, name); /“open existing system semaphore*/ 


80eeee 


This gives you the handle of that semaphore if hSem is not null on return, 
but does not establish semaphore ownership. Once you have the handle all of 


é 


the above calls are valid. 


RAM SEMAPHORES 
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A RAM semaphore is simply a double-word of storage. You can simply _) 
address the word as a global variable, and you can use the above calls to. 
operate on it. While it is possible for another process to get access to the 
address of a RAM semaphore, you should not use RAM semaphores ~ 
between processes, but only between threads of the same process. Since a\_) 
RAM semaphore is just a word in your program’s memory, there Is no possi- | 
bility of tracking semaphore ownership, and your program must use it as a 
local flag with whatever meaning it wants to define for it. Note, however, 
that you can use the DosSem functions to clear, set, and wait fora RAM\) 
semaphore to clear. The only changes we need to make in the above programy ) 
are the use of the address of the RAM semaphore instead of the handle of a 
system semaphore: | 


ULONG ramsenm; /*RAM semaphore | 
icin aie mei meas can en pecimiennmaus anemia aimiamnmmienteaeiainam a 
void main() 
begin 

unsigned char “stack; 

HSEM hSem ; 
ramsem = 0; /*initialize RAM semaphore*/ 
DosSemSet (&ramsem) ; /*set the semaphore high “*/ 


/*Create a semaphore clearing thread */ 
stack = malloc(2000); /*get stack space 
_beginthread(SemCIr, stack, 


2000, &ramsem); /*pass address of semaphore”/ 
DosSemRequest(&ramsem, -1L); /*block thread a J 
/*until we can set sem oF | 

printf("Exiting \n'); /*“exit message * / 
DosExit(1, 0); /*end all threads a 
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end 
| i Os a a a ys soe na WS nw enh Se Se mk aS ae ed sn * / 
/* waits 2 seconds and clears sem * / 
j* —---- - - - ~~ ~~ ee ee en nr en ne ne nr er rrr rrr * f 
void SemCIr( HSEM “hSem) 
begin 
©) Dos$ leep(2000L) ; /*wait 2 seconds as J 
am DosSeml lear (hSem) ; ' /*and clear the semaphore */ 
end 


o 
RAM semaphores provide a small performance advantage since the 
program operates directly on the address of the semaphore rather than a 
™) handle which must be resolved into an address. 


“y 


2 Fast-Safe RAM Semaphores 
mo, 


A Fast-Safe RAM semaphore is a compromise between the system 
semaphore, where ownership is tracked and the standard RAM semaphore 

©) where it is not. The FS RAM semaphore is a 14-byte structure of type 

« DOSFSRSEM which contains fields for ownership. It also includes a count 
field, so that it can be accessed recursively. It can be accessed by threads of 
different processes, but it is located in the memory of one of those processes. 
Thus, the only way that this can be accomplished is if the FS RAM 

y semaphore structure is placed in a shared memory segment. Shared memory 
is discussed later in this chapter. FS RAM semaphores have only two 
allowed calls: 


oy DOSFSRamSem€ lear (&Fsram) ; /*clear an FS RAM semaphore*/ 


©) DosFSRamSemRequest(&fsram, 
amy timeout); /*request ownership of FS RAM */ 


™) where the structure of the fsram semaphore is DOSFSRSEM: 


M) typedef struct DOSFSRSEM { 


USHORT cb; /* length of this structure P| 
PID pid; /*Process ID of the owner or zero*/ 
TID tid: /* Thread ID of the owner or zero”*/ 
USHORT cUsage; /* Reference count *Y 
USHORT client; /* 16 bit field for use by owner */ 
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ULONG sem; /* 0S/2 Ram Semaphore oy 
} DOSFSRSEM; 


Purposes of Various Semaphores 
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RAM semaphores are designed primarily for signalling one process that(_) 
another has completed some task, while system semaphores are designed for, 
resource control: to indicate that some resource is now available. When a 
semaphore is used for signalling, the semaphore is never owned, and any 
thread can clear or set it at will. If two processes control access to a\_) 
resource, such as an interface card, using system semaphores, then if one, 
process terminates, the other wi// be able to access the semaphore and gain 
access to the resource. This is not true of FS RAM semaphores, where ter-~ 
mination of one process could leave the other hanging indefinitely waiting\_) 
for the semaphore to clear. | 
YY 
‘7. 
COMMUNICATING WITH PIPES ‘3S 


OS/2 allows you to pass data between threads using both unnamed and 
named pipes. An unnamed pipe is like a file that can be written into by oneWw 
thread and read back by another thread. Unnamed pipes can only be used(_) 
within one process as a substitute for intermediate file I/O, but named pipes, 
can be used between processes. Pipes are limited in size to 64K bytes, 


although they are frequently as small as a single line of characters. WY 
‘2 
Unnamed Pipes Y 
WY 
Unnamed pipes are used primarily for sending file information betweengmy 
threads without actually writing to disk. You create an unnamed pipe using 
the call Ww 
/*create an unnamed pipe yw 
DosMakePipe(&hRead, &hWrite, MAXLEN); , 


where hRead and hWrite are the returned read and write handles and\y 
MAXLEN is the size of the pipe. Then, you write into the pipe using) 
DosWrite and read from it using DosRead. You can also use the asynchro- 
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™) nous read and write commands that do not wait until data are available. The 
om following simple program illustrates the use of unnamed pipes: 


@ void main() 
begin 
: unsigned char “stack, buf[MAXLEN]; 
O) HFILE hRead, hWrite; 
a, int read; 


)DosMakePipe(&hRead, &hWrite, 

a, MAXLEN) ; /*create an unnamed pipe*/ 
stack = malloc(2000); /*get stack space ae 
_beginthread(PipeWrite, stack, 

2000, hWrite); /*pass address of write hnd*/ 
DosRead(hRead, buf, 


. MAXLEN, &read); /*‘wait for read ay 
Mprintf(''%s'', buf); /*print out text read “*/ 

DosClose(hRead) ; /*close the pipe | 
WDosExit(1, 0); /“end all threads oy 
Mend 
gg) oreo ‘ 

/* writes text into a pipe and returns “7 
O)/*------------------------------------- 2-2-2 22-2 --------- e/ 
avoid PipeWrite( HFILE hWrite) 

begin 

int written; 

™, char buf[MAXLEN]; 

strcpy(buf, ‘Writing to a Pipe\n'); /*“message to write*/ 
~_ DosWrite(hWrite, buf, 
om, strlen(buf), written); /*write to pipe “*/ 
apPosClose(hWwr ite) /*close pipe ay 


OW 


/*and end thread */ 
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Named Pipes 
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Named pipes are designed for more sophisticated communication between 
processes, although they can be used within threads as well. A named pipe\ > 
must be created using DosMakeNmPipe having the subdirectory prefix, 
\PIPE\ followed by a normal filename. Once a pipe is created, you can 
block the current thread waiting for another thread or process to connect to 
it with DosConnectNmPipe. WY 

Named pipes can send data as byte streams or as messages. A message, 
pipe has a header associated with it that contains the length of the message 
that follows. These headers are added by DosWrite and removed by 
DosRead so you needn’t manage them yourself. Byte stream pipes send\~ 
bytes without any associated size information. Pipes can be one-way or full) 
duplex, and reading and writing then takes place using the same handle. 

To create a named pipe, you use the function 


DosMakeNmPipe(name, &handle, openmode, pipemode, 

osize, isize, timeout); 
where 
name is the name of the pipe. It must be prefixed with \PIPE\. 
&handle is the location where the pipe handle is returned. 


openmode contains the open mode bits 


15 14 1312 1110987654 
0 W ----------1000 


where W is | if network buffering is not allowed and 0 if 
network buffering is allowed; I is 0 if spawned processes can 

inherit the pipe handle and 1 if they cannot; and AAA controls 
the access to the pipe. 


Geeeeeeeoc 


000 ‘read only pipe 
001 write only pipe 
010 duplex pipe 


pipemode controls the pipe transmission mode: 
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Bee ae ON Ree veoh | 


B is 0 if the pipe is to be blocked if no data are available 
and | if the pipe is to return immediately if no data are 
available. 


TT write mode: is 00 if this is a byte stream pipe and 01 if 
this is a message stream pipe. 


RR __ read mode: is 00 if the pipe is to be read as a byte stream 
and 01 if the pipe is to be read as a message stream. 


count is the number of instances of that pipe that can be 
created. 


is the number of bytes recommended for the outgoing buffer. 


990999990900090909900 


_ /isize is the number of bytes allowed in the incoming buffer. 

timeout is the number of milliseconds to wait for DosWaitNmPipe. If 
‘ab this is zero the system default of 50 msec is chosen. 
om 


When the pipe has been created, you can then wait for the other thread 
)or process to connect to it with the call 


an, 


err = DosConnectNmPipe(hPipe) ; 


‘This call will block the current thread until a connection is made if blocking 
mode is set, or returns immediately with err non-zero if blocking is not set. 
omThe following simple program illustrates the named pipe calling sequence: 


/*----- connect 2 threads using a named pipe ------------ ey 
avoid main() 
begin 


©) unsigned char “stack, buf[MAXLEN]; 
g 
om,  HPIPE hPipe; 
| int read, err; 


qDosMakeNmPipe(''\\PIPE\\dream.pip', /*open a named pipe */ 


&hPipe, /*return handle here*/ 
Ox2., /*duplex pipe a 
0x0001, /*byte pipe a 
MAXLEN, MAXLEN, /*“size of buffers */ 


963300 


292 COMMUNICATING BETWEEN OS/2 PROCESSES AND THREADS 


0); 


/*Create a semaphore clearing thread 


stack = malloc(2000); 


_beginthread(PipeWrite, stack, 
2000, OL) 


err = DosConnectNmPipe(hPipe); /*wait for pipe connection*/ 


DosRead(hPipe, buf, 


MAXLEN, &read); /“read a message from the pipe*/ 
/*“print it out a 
/*and close it i 

/ 


printf(Zs . buf): 
DosClose(hPipe) ; 
DosExit(1, 0); 

end 


void PipeWrite() 
begin 


int written, action, err; 


char buf[MAXLEN ]; 
HP IPE hPipes 


err = DosOpen(''\\PIPE\\dream.pip., 
EhPipe, 
Eaction, 
80L , 


0, 
1, 


Ox2012, 
OL); 


DosWrite(hPipe, buf, 


strlen(buf), S&written); 


DosClose(hPipe); 
end 


SHARING MEMORY SEGMENTS 


/*default timeout a 


* / 
/*get stack space “*/ 


/*pass address of semaphore”/ 


/*“open same named pipe” 
/*action taken 

/*size 

/*attr ibutes 

/“open flag 

/*“open mode 

/*reserved 

strcpy(buf, “Writing to a Pipe\n'');/*copy message 


/*‘write it to pipe 
/*then close it 
/*end thread 


threads 


a a ee 


sh 


se 


sh 
“y 


o0cbdddeSccccccc cc ccceccececee 


Memory segments (up to 64K) can be allocated and shared between proc 


esses in two ways: as shared segments and as named shared segments 
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emShared segments can be addressed by any created child processes, and 
named segments can be shared by processes created in any session. 


- 


om 
ashared Memory Segments 


‘ The following calls are used to allocate and share segments with child proc- 


Orsses: 


m 
abosGiveSeg(callseg, bid, /*give access to segment * 
&recipseg); /*as recipseg * / 

om 
mPosGetSeg(seg); /*get access to segment a 
DosGetPID(&pidinfo) ; /*get proc id */ 
JosGetPPID(pid, éparpid); /*get parent's process id “*/ 
MosAllocSeg(size, &seqg, /*allocate memory; oF 
flags); /*return selector a 
JosFreeSeg(seg); /*deallocate memory segment aad 


Memory segments allocated with DosAllocSeg can be shared by calling 
DosGiveSeg and obtaining the selector for the child process. Then, this 
(elector is passed to the child process using a named pipe or queue. The 
child process then calls DosGetSeg and the memory is then sharable between 

the two processes. The memory is only released when DosFreeSeg has been 
__talled by both processes, or when both have terminated. 


om 


O\Named Shared Memory Segments 

o 

Analogous to named pipes and semaphores is the concept of named shared 
memory segments. Such segments are allocated with DosAllocShrSeg and 

“ure accessed by other processes using DosGetShrSeg.: 


JosAllocShrSeg(size, name, &sel); 
MyosGetShrSeg(name, &sel); 


<x 
= 
@) 
r=} 
ca) 


N 
@ 


is the number of bytes (<64K) to allocate. 
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name is the name of the shared segment. This must have the 
subdirectory prefix \SHAREMEM \ and be followed by 
a standard filename. 


€ 


& sel is the selector value allocated or shared. 


QUEUES 


68eee 


A queue is a named buffer that has data put in by one or more processes an(_) 
that can only be read out by the owning process. The purpose of a queue is t¢ 
send information to the owning process for action, such as requesting the 
services of a device. | 


\J 

YU 
Queue Ownership Y 
WY 
The process that creates the queue is considered the owner, and can execul@® 
any of the following calls: 


DosCreateQueue(&hQ, priority, name); 
DosPeekQueue(hQ, &req, length, address, 

elementcode, nowait, priority, hSem); 
DosReadQueue(hQ, &req, length, address, 

elementcode, nowait, priority, hSem); 


a, 
a, 


DosPurgeQueue(hQ) ; 

DosQueryQueue(hQ, &size); 

DosWriteQueue(hQ, req, length, address, priority); 
DosC loseQueue(hQ) ; 


Writing to a Queue 


©0006 ¢ 


A thread of the owning process or any other process can write to a quev 


using the calls 


DosWriteQueue(hQ, req, length, address, priority); 
DosQueryQueue(hQ, &size); 

DosOpenQueue(ownerpid, &hQ, name); 

DosC loseQueue(hQ) ; 
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om, 


emAny process other than the owning process must first call DosOpenQueue. 
athe queue name must include the \QUEUES\ prefix. The semaphore used 

in DosReadQueue is cleared when data are placed in the address specified. 
Ot can be either a system or a RAM semaphore. The priority defined in 
cM™osCreateQueue determines whether a queue is read first-in first-out (FIFO 


oo 0), last first (=1) or by individual element priority (2). 


on, 
@lHREADS AND MESSAGE QUEUES 


Orne communication techniques we have illustrated in this chapter can be 
sed to communicate with threads that do not have a message queue. A 
q@bhread with a message queue is usually one that supports windows and 
receives messages. Such threads must obey the 0.1-second rule and cannot 
“spend a lot of time performing calculations. Therefore, such threads cannot 
hang” waiting on a semaphore or pipe data value, since this will block the 
qhread and prevent messages from being processed quickly. Instead, you 
agiiould post messages to such threads as we did in the previous chapter. 
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21 Elements of Assembly 
Language Programming 
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The fundamental reason for writing a routine in assembly language is to 
emandle bit and address manipulation when it dominates over numeric calcu- 

lation, as is usually the case in system and interrupt routines. Such manipu- 

.ations may be faster in assembly language because you can select the 
yhinimum number of integer instructions to get the job done without having 
amhe overhead that the compiler may impose on such calculations. For 
example, you can keep all the important values in registers and never store 

chem back into memory unless they are actually needed later. In addition, 
Mhterrupt service of device registers may not be possible any other way while 
o™till preserving rapid interrupt response. 


ao 


©THE 80X86 MICROPROCESSOR FAMILY 
om 
Che original IBM PC was built around the 8088 microprocessor, which has 
ae instruction set we will be discussing here and an 8-bit data path to and 
yom the chip. The 8086 microprocessor is a somewhat more efficient imple- 
mentation of the same instruction set and has a 16-bit data path to and from 
the chip. 
The 80286 microprocessor is the chip used in the Personal Computer AT 
PC/AT) and and the PS/2 Models 30-286, 50 and 60. It has the same 


struction set as the 8088 in real address mode, but with a few enhance- 
o 
(> 
m 
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ments, considerably faster operating speeds, a 16-bit data path, and in pro 
tected address mode the ability to address up to 16 megabytes of memory. 

The 80386 microprocessor is the chip used in the PS/2 Models 70 and 8 
as well as in a number of machines with the “386” designation in thei__ 
names. It runs even faster than the previous generation and has much mors 
sophisticated additional processor modes. It has a 32-bit data path and can 
address up to 248 bytes or four gigabytes of memory. It also will operate as ~ 


very fast 8088 processor in real address mode. Ly 
Y 
INSTRUCTIONS AND DATA YU 


Memory in the 80x86 family is organized into 8-bit bytes. Two bytes iilee 
up a 16-bit word, and most integer operations take place on 16-bit words. lire 
digital computers, an instruction pointer (IP) register is set to contain thw 
address of some memory location where numbers called instructions at 
stored. Locations that contain instructions are no different than location> 
that contain other numbers except that the programmer tells the compute 
to begin executing the numbers at some address and continue executiny 
from that point. Obviously, if a computer begins executing locations cor) 
taining data values, it will probably behave strangely, usually resulting in¢ 


crash. 
WwW 
ORGANIZATION OF THE 8088 INSTRUCTIONS = 
VU 


( 


The 8088 microprocessor is fundamentally an accumulator machine \__ 
which the four registers AX, BX, CX, and DX can be used as places to p} 


values and carry out calculations. Each of these registers is 16 bits wide ant 
can be broken into two 8-bit registers: Y 
wy 
16-bit 8-bit ‘? 
AX AH, AL 
BX BH, BL ad 
CX CH, CL WY 
DX DH, DL J 
eS 


These “general” registers also have special purposes inherent in their nam 
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om 
maxX Accumulator register 
( “BX Base register 
CX Counter register 
om, 
OX Data register 
am 


You can carry out 8- or 16-bit operations depending on whether the instruc- 
‘ion refers to the 8- or 16-bit register name. 
©) As noted earlier, the 80xxx has a segmented address scheme in which a 
6-bit address can refer to 65,536 bytes of memory relative to a segment 
register. These registers are assumed to point to the code, the data, the 
~ 3tack, and to another “‘extra”’ data set: 


o_ 

CS Code segment register 
Oo 

DS Data segment register 
> & g 
aS Extra segment register 
oss Stack segment register 


@YThus, while the basic 8088 instruction set can only address 65,536 bytes 
ofirectly, you can change a segment register so that you can address 1 mega- 
byte of memory or 1,048,586 bytes. This 1-megabyte limit is enforced by a 
20-bit internal address bus: the 80286 and 80386 have much larger potential 
(ddress spaces, but not when running the instruction set and addressing 
cemodes of the 8088 chip. It is this 20-bit limit that leads to the 640K limit on 
a PC’s memory running in real mode, where the upper 384K of the | mega- 
Jyte are reserved for the addresses of the video screens and the read-only 
Mhemory, which make up the basic input/output system (BIOS) code of the 
ec. This 640K limit applies only under DOS, however, since OS/2 runs in 
he 80286 protected mode. 
| The actual address of any memory location is made up of a segment reg- 
ter value and an offset. A segment address is simply the absolute 20-bit 
smddress with the lowest 4 bits dropped. Therefore the address of the EGA 
creen memory is A0O00,, and the segment address is just OxA000. Thus, 
only every 16th address can be described directly by a segment register 
alue, and these addresses are called paragraph addresses. In the protected 
(node, these registers actually refer to descriptor table locations and offsets. 
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If we want to refer to a given location relative to a segment address, w 
usually write a 32-bit number with a colon between the upper and lower 1 
bits: a000:0123 means address a0123. 

The other registers in the basic 80x86 are two index registers and tw¢_) 
pointer registers: | 


eseecec 


‘= 
SP Stack pointer ‘o. 
BP Base pointer Cy, 
SI Source index a, 
DI Destination index VY 


j 


, 


Each of these has special purposes, as we will see in the examples tha 
follow. 


FUNDAMENTAL MACHINE INSTRUCTIONS 
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There are a number of instructions for carrying out arithmetic and logica, 
operations in the 80xxx microprocessor, but we will only mention a few 

common ones here. Most are dual operand instructions: they have two parts 
a source operand and a destination operand. The source operand is neve) 
changed and the destination operand is almost always changed. The synta® 
of these two operand instructions 1s 


{ 


~— 
opr dest, source ;perform operation On source 


; and put in destination 


Note that unlike some other instruction syntaxes, the destination operand is 
written first, followed by the source operand. Note that comments in 
assembly language always start with semicolons, unlike in C where “*/*” 0) 


““//? symbols were used. @ 
Y/ 
CAPITALIZATION IN ASSEMBLY LANGUAGE oe 


The MASM assembler program recognizes instructions in either uppercase” 
or lowercase as being equivalent. We will follow Microsoft’s recommendew 
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@sonvention and write all of our instructions in lowercase and all of the direc- 
afives that tell the assembler how to carry out the assembly in uppercase. 


J 


DUAL OPERAND INSTRUCTIONS 


some of the most common dual operand instructions include: 


om 
mov b, a ;move A to B 
on add b, a ;add A to B 
a Sub b, a ;subtract A from B 
| xchg b, a ;swap A and B 
om and b, a sAND A with B 
am OF Bs a ;OR A with B 
xor b, a ;exclusive OR A with B 
om 
om, cmp b, a ;subtract A from B and set 
on ; the condition flags 
om test by a ;AND A with B and set 
om ; the condition flags 


mn each case the source A and the destination B may be registers or memory 
ddresses, but both cannot be memory addresses. To move a value from one 
uddress to another, you must first move it to a register and then move the 
Ogister to another memory address. There are also multiplication and divi- 
oon instructions, but they are seldom necessary since such operations are 
usually better written in C. 


om 
@SINGLE OPERAND INSTRUCTIONS 


Mome of the most common single operand instructions include 
inc a ;add 1 to A 
dec a ;subtract 1 fromA 
neg a ;negate A 
not a ;take ones complement of A 
jmp x ; jump to location named ''x'! 
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SHIFT INSTRUCTIONS 
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Shift instructions move the bits in a register to the right and left. The bits on 
the end fall off and are lost in the chronosynclastic infundibulum. A logical) 


shift causes the bits on the source end to be filled with zeroes. 


A right arithmetic shift causes the sign bit (bit 15) to be copied into eac 


of the vacated leftmost bits. 
iS 14.12 12 17 10 9 8 7 6 SE Se 1 8 


COTE 


right logical shift 


15 141312 1110 9 8 7 6 5§ 4&4 3 2 1 «0 


« ~LE ELT TTT 


left arithmetic or logical shift 


IS 4 13121110 9 @ 7 6 & & 3 2 1 8 





lost 
right arithmetic shift 
The shift instructions have the syntax 
Sal a, 1 ;shift A 1 place left 
Sal a, Cl sshift A left the number of place 


;contained in register CL 


snr a, 1 ;logical shift A right 1 place 
Shr a, cl ;logical shift A right by CL 

Sar a, 1 sarithmetic shift A right 1 place 
sar a, cl sarithmetic shift A right by CL 


ROTATE INSTRUCTIONS 


_) 
h 
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There are also four rotate instructions in which the data are rotated out Y 
one end of the register and into the other. Two of them also include the carry 


flag register in the rotation. 
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5 1 13 1211. 0 § 8 7 6 S&S + % 2 1 BD 


right rotate - ROR 


15 1413121110 9 8 7 6 GS 4 3.2 1 08 CF 


right rotate through carry - RCR 


J 


) 


if 1413 12 1170 9 8 ¥F a 54 32 1 0 


eel 


left rotate - ROL 


d 


15 1413 12 1110 9 8 7 6 5 4 3 2 «1 «0 LF 


pu 


left rotate through carry - RCL 
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THE FLAG REGISTERS 


) 


(The 8088 processor has a set of six 1-bit flags that are used to monitor the 

a@mesult of the last executed operation. These flags can be tested as part of 
conditional jump instructions to make decisions that control the flow of the 
program. 


pao) Carry flag. Set if there is a carry out or borrow in. 
alt Zero flag. Set if the result is zero. 
ask Sign flag. Set if the result is negative. 


Overflow flag. Set if the signed result is out of range. 


23 


Parity flag. Set if the result has an even number of bits set to 1. 


4 


Aux carry flag. Set if there is a carry out from the low 4 bits to the 
high 4 bits of the lowest byte of the operand. 
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DECISION-MAKING INSTRUCTIONS 


The conditional jump instructions test one or more of the flag register bits 


/ 
WY 
WwW 
YW 
WZ 


VW 


and jump if and only if the condition tested for is true. These flag bits aré 
set by arithmetic operations and by CMP and TEST instructions, but not by_) 


MOV instructions. 


jmp x 
je 
jnc 
je 
JCxz 


; jump 
; Jump 
; jump 
; jump 
; jump 


Signed comparisons: 


Unsigned comparisons: 


jne 
Jg 
jge 
jle 
jl 


ja 
jae 
jbe 
jb 


; jump 
; jump 
; jump 
; jump 
; jump 


; jump 
; jump 
; jump 
; jump 


always 


if 
if 
ct 
if 


if 
if 
if 
it 
it 


if 
if 
Ga 
if 


carry 


not carry 


equal zero 


cx iS zero 


not equal to zero 
greater than 


greater than 


or equal to zero 


less than or equal to zero 
less than 

above 

above or equal 

below or equal 

below 


THE LOOP INSTRUCTION 
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The LOOP instruction is used to loop through a small section of coder” 
extremely quickly. Each time the loop instruction is encountered, it decree 
ments CX by | and loops back to the specified address if CX is non-zer¢_, 
When CX becomes zero, the loop is completed and the next instruction YY 


executed: 
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mov cx, 5 
10: mov dx, ax 


;set counter 

;copy AX into DX, for instance 
sother instructions 

;go back until CX is 0 


9 e 


loop cl0 


0.990999 


( There are also two special forms of the LOOP instruction that are useful for 
Pp 
omearching a table for the first zero or non-zero element: 


o LOOPE addr ;loop until ZF is set or CX is zero 
om LOOPNE addr ;loop until ZF is clear or CX is zero 
O 


@ADDRESSING MODES IN THE 8088 


Ornus far we have discussed the various 8088 registers and the condition 
(lags, but have not discussed how we can address memory locations using the 


anrevious instructions. The 8088 has seven basic addressing modes: 


om mov ax, bx ;register addressing 
ab, mov ax, 5 ; immediate addressing 
oO 
Om mov ax, fred ;direct addressing 

i mov ax, ds:010h 
Oo 
oOo mov ax, [di ] ; indexed indirect addressing 

mov ax, [si] 
Oo mov ax, [bx sbased indirect addressin 
g 
om, mov ax, [bp] 
> mov ax, [bp+6] sbase relative (6 off BP) 
o mov ax, 6[bp] sbase relative also 6 off BP 
a> mov ax, [bx-12] ;base relative 
mov ax, [di+20] ;direct indexed 

on mov ax, [sit+33] ;direct indexed 
% mov ax, [bx][di ] ;based indexed 
oO mov ax, [bp][di] 
on mov ax, [bx][si] 
_ mov ax, [bp][si] 
o 
a 
a 
om 
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mov ax, 12[bx]|[di] ;based index with displacement 
mov ax, 25[bp][di ] 
mov ax, 42[bp][si] 


Seeede 


In all of these addressing modes, the segment register is assumed to be the.’ 
DS register unless the BP register is used in the instruction. Using the BR 
register always implies that the SS register is used. In most cases, these reg- 
isters are loaded for you by the calling program and you seldom have to loa 
them or be aware of their contents when writing subroutines to be callea/ 


from C. i 
oO 
Register Addressing CL) 


In this mode, the data are in one of the registers. In the first example above. 
the BX register is the source, and in all of the examples, the AX register ise 


the destination. er, 
WS 
Immediate Addressing WY 


In this mode, a 16-bit constant is moved into a register. The constant is actu- 
ally stored in a second location just after the instruction. Obviously, thes 


constants can only be used as source operands. a, 
WY 
Direct Addressing WwW 


Direct addressing is almost always used when a program wishes to move 
data to or from a memory location nearby. This could occur for local con 
stants that are accessed from a number of places or when a routine uses loca) 
data storage for temporary results. In MASM syntax, a named or labelle 
location must start with an alphabetic character or with an underscore (_) 

a question mark (?), a dollar sign ($), or an “at” sign (@), and the laber” 
may be up to 31 characters long. You define a location as having a name buy 
placing the name on a line followed by a colon. You use a name by simp\_) 
referring to it as an address: 


VS 
Ww 
‘Ss 
Ww 
Ww 
Not 
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mov bx, tem32 ;get contents of location TEM32 
;and put in the BX register 


3900090 


rem32: 03456h ;address containing a constant 


OVsually, such labelled addresses are nearby in the code and are referred to 
oms NEAR, meaning that they are addressed as part of the code segment 
ointed to by the CS register. This will always be true in the simple exam- 
ples in this chapter, but it is possible to refer to FAR labels where another 
/egment register is implied or used specifically. 


om 


Based and Indexed Indirect Addressing 
ao 
n both of these addressing modes, a register contains the address of the 
memory location of interest. Unless a segment register is specified, the 
issembler assumes that the segment is pointed to by DS and the register 
)ontains an offset relative to this segment address for addresses pointed to 
aby BX, SI, or DI. If BP is used, the stack segment register SS is assumed. 
Che purpose of these modes is to calculate a pointer address that can be used 
_.o refer to a data location. Often these addresses are incremented or decre- 
ented in a loop so that a table of addresses can be referred to sequentially. 
am\his provides a way of stepping sequentially through an array. 


on 
oase Relative and Direct Indexed Addressing 


O. both of these modes, a register contains a fixed address and an offset is 

becified that is added to this register to calculate the final address. Several 

lightly different syntaxes have evolved over the history of the 80xxx 

ger OCeSSOTS, and all are accepted by the current MASM assembler as iden- 
cal: 


om 
mov cx, 6[bp] ;all refer to the same operation: 
mov cx, [bp + 6] ;get contents of address 6 off bp 
MM) mov cx, [bp] + 6 sand put it in cx 


each of these examples, 6 is added to the contents of the BP register to 
cfgrm a new address. This address is the one used to retrieve the data. Since 
ae is used, the stack segment (SS) register is implied. The purpose of these 


om 
” 
om 
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modes is usually to fetch a value from a table of values passed to a subrou(_) 
tine, where the start of this table is pointed to by the base register. 


/ 
s VU 
Based Indexed Addressing | 
WY 
In this mode, the contents of a base register BX or BP are added to the con 
tents of an index register SI or DI and a specified constant offset is added ty 
this to form the effective address of the data. If BX is used, DS is implied 
and if BP is used, SS is implied. As above, there are a number of equivalent 


syntaxes: / 
mov dx, [bp] [si] + 12 sequivalent syntaxes VY 
mov dx, 12 [bp] [si] ; for based index addressing\) 


mov dx, [bp + ‘si +412] 


mov dx, [bp][si + 12] Y 


The main purpose of this mode is really to access elements in a table aoe 
fixed-length records. If BP contains the address of an array of records ana 
SI contains the offset to a given record in the table, then the displacemenW 
(12) is the number of bytes to the address of a given element in that record.(_) 


LU 
THE STACK a 


The stack is an array of numbers pointed to by the stack pointer register. Ir 
is used for temporary storage of data passed to subroutines and for the 
return addresses from subroutine. The stack pointer always starts at a hig.) 
memory location and grows toward low memory (address 0). The SP reg, 
ister always contains the address of the last value pushed onto the stack. For 

each value pushed onto the stack, the stack pointer is decremented by 2, ane 
a value is put in the location whose address is represented by SS:SP. F«_) 
each value popped off the stack, a value is moved from the address SS:S/ ) 
and put into a destination register; then the stack pointer is incremented by 

Ze 
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push ax ;put the contents of AX onto the stack 
push bp ;put the contents of BP onto the stack 
pop bp sretrieve old value of BP from the stack 
pop ax ;get old AX value from the stack 


}900090909 


The address in SS and SP is usually controlled by the calling program and 
~ does not need to be calculated in your subroutines. However, if you push 
OWalues onto the stack, you must retrieve them before exiting so that the stack 
pointer has the same value when you leave a subroutine as it did when you 

entered it. 

Oo 
om 
CALLING SUBROUTINES IN ASSEMBLY LANGUAGE 


. he CALL instruction is used to call subroutines in assembly language. This 
™ynstruction saves the address following the call on the stack and then jumps 
ano the address named in the instruction: 


am call ztest ;call ZTEST subroutine 


(This has the effect of 


Oo push IP ;save the instruction pointer 


am jump ztest ; jump to address ‘‘ztest' 


(he reason why this instruction 1s so powerful is that it gives us a way to call 
routine from many places and return to those locations after executing the 
subroutine, since the address we came from is saved on the stack. 
Of course, there must be a complementary instruction to return to the 
ddress following the call 


oy ret 


sreturn to the address on the stack 


Ore RET instruction pops the address of the stack and puts it into the IP, so 

(hat the next instruction fetched is that at the new address in the IP, thus 

qmsausing a return from the subroutine to the address after the original CALL 
Statement. 
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NEAR AND FAR PROCEDURES 
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C 


Since the 80xxx addresses are always made up of a segment value and a 
offset value, the “‘true’’ address of any procedure is also 32 bits long, made’ 
up of a segment and offset. Therefore, if you call a procedure, it may be in_) 
the current segment or in a different 64K segment of memory. We call a 
procedure in the same segment a NEAR procedure and one in another 
segment a FAR procedure. To call a FAR procedure, we need to save both 
the code segment register CS and the current address offset in IP on thé_) 
stack, and load new values into the CS and IP. Likewise, to return from a \ 
FAR procedure, we need to pop both of these values off the stack. 

The MASM assembler has NEAR and FAR directives to be used with 
each subroutine so that it can decide whether to generate a near or a far cali_» 


and return for each procedure: & 
ztest: PROC NEAR sthe near subroutine starts here WC 
/ 
Fret ;return from a near procedure / 

ENDP stell MASM this is the end of ZTEST, 
YZ 
ftest: PROC FAR -start of far procedure WY 
WY 
ret sthis will be a far return WY 
ENDP ;tell MASM this is the end of FTEST () 
We will see the uses of the stack and PROC directives in the following / 
chapter. ‘o 
WY 
THE STRING INSTRUCTIONS YO 
oe, 


The 8088 series also has a set of instructions for transferring blocks of dat 
from one location to another. These instructions are very efficient ways Om 
moving, comparing, and scanning strings of up to 64K bytes in length. Actu_) 
ally we refer to “strings” for these instructions, although the compilers oftey 
use these instructions for moving many types of numbers from one place to 
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another. We will not use them in our programming examples but merely list 
amthem here for completeness: 


om movsb ;move string of bytes 
Ps mov Sw ;move string of words 
o, cmpsb ;compare string of bytes 
m cmpsw ;compare string of words 
Oo scasb ;scan string of bytes 
“am scasw ;scan string of words 


™) Each time one of these instructions is executed, one element of the string 
as moved, compared, or scanned, and SI and DI are changed by | or 2. The 

entire operation can be carried out in a single pair of instructions by adding 
he REP prefix to the instructions: 


em, 

rep movsw ;move entire word string 
om repne cmpsb srepeat while not equal (zf=0) 
am repe cmpsb ;repeat while equal (zf=1) 


@™)_ Ineach of these instructions, the length of the strings is contained in CX, 
the address of the source string in DS:SI, and the address of the destination 
string in ES:DI. The strings can be scanned from low memory to high 

Oynemory or vice versa, depending on the state of a special flag called the 

omvirection flag. If the direction flag is 0, the SI and DI registers increment 

alter each use, and if DF is 1, they decrement. 


on CLD ;clear direction flag 
STD ;set direction flag 

- 

rs 


MULTIPLE REGISTER LOAD INSTRUCTIONS 


‘ Two instructions are commonly used to load a segment and an offset register 
amuimultaneously: 


on LDS reg, ea ;load data segment 
LES reg, ea ; load extra segment 


am 
o> 
Oo 
m 
Ps 
Mm 


/ 
VW 
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Both of these instructions get 4 bytes from the effective address: two that gory ) 
into the segment register and two that are loaded into the specified destina- 
tion register. 

This concludes our brief summary of the 80xxx assembly language. In\/ 
the following chapters we will show how C and assembly language can bef ) 
interfaced in device drivers. 
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OPERATING MODES OF THE 80286 


(The 80286 microprocessor runs in two modes: real mode (8086 mode) and 
mprotected mode (80286 mode). In real mode, the processor runs as if it were 
an 8086, limited to addressing a single 1-megabyte address space. In pro- 
‘tected mode, the microprocessor can address a 16-megabyte address space 
and has a substantial number of features to allow multitasking. It further 
emallows complete protection of each job’s code and data space from interfer- 
ence by other jobs. 
This protected mode is actually divided into four rings numbered from 0 
o 3, with successively more protection. Most programs run at ring 3, where 
am™hey have no I/O or interrupt privileges, and the OS/2 kernel and device 
drivers run at ring 0, with both interrupt and I/O privileges. If you want to 
access a device using IN and OUT instructions, but do not need to use inter- 
Orupts, you can write code in a special segment with I/O privileges, which 
@yuns in ring 2. OS/2 makes no use of ring 1. Because of this protection 
cheme, you must write a device driver if you want to access the device at 
interrupt level. 
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WRITING AN IOPL SEGMENT PROGRAM 
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If you only need occasional access to the ports of your device and do not 


need to control or respond to interrupts, you can write a program that con-\/ 
tains an JOPL segment. Such a routine can be written entirely in C except(_) 
for the routine that actually accesses the ports of the device. This routine, 
must be written in assembly language, although it may be quite short and 
simple. You cannot write a routine that uses the C library functions inp and” 
outp to access the ports since these routines lie in a segment linked to your\_) 
program that does not have IOPL privileges and does not run at ring 2. 

To illustrate how we can write such a routine, we will use the example of 
the Metrabyte ucDAS-8PGA card which is normally set so that the 1/ow 


ports have the following definitions: ae, 
Address Read Function Write Function | 

300 A/D Low byte Start 8-bit conversion ~~ 

301 A/D High byte Start 12-bit conversion 

302 Status register Control register ‘o 

Yo 


To start a 12-bit A/D conversion, we write any value to port 301. To see | 
if the conversion is done, we look at bit 7 of the status register. If it is 1 thew 
conversion is still in progress and if it is zero the conversion is complete. The_) 
converted data can then be read from ports 301 and 300. Port 301 contains 
the top 8 bits and port 300 the bottom 4 bits. A simple assembly routine for 
starting the ADC and reading the result into the AX register is shown 
below. 


TITLE READADC 
.286p 

-MODEL LARGE 

CODE 


- int readadc() 
; define bytes for port access 


PORT 1 EQU 300h 
PORT2 EQU 310h 
PUBLIC _readadc ;reads one value from adc 
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ap_readadc PROC 


mov 
oy out 
inc 
Q@waiti: in 
om test 
jne 
a, mov 
om in 
on mov 
Ww dec 
eo in 
lan’ shr 
ret 
©) readadc 
on 
a” 
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FAR 
dx, PORT1+1 


dx, al 
dx 

al, dx 
al, 080h 
wait] 
dx, PORT 1+1 
al, dx 
ah, al 
dx 

al, dx 
ax, 4 


ENDP 


sadc start location 
;sending any byte 

swill start the adc 
;portt+2 is status byte 
;check status 

;is ADC busy bit set? 
swait until it goes low 
;now read upper byte of 
;converted result 

;Save in ah 

sport to read lower byte from 
;get lower byte 

sshift both 4 bits right 
sand exit 


m The C-language routine that calls READADC is the simple 


em#include <cdefs.h> 
#define INCL BASE 
#define INCL DOSDEVICES 


OM include <os2.h> 
#include <stdio.h> 


on 
OWoid main(); 


aint readadc(); 


/*assembly language routine a 


/*in 1OPL segment =) 
oy Pa tS a me oe a my a ay ti a dc * / 
an” illustrates reading from a device port using 0S/2 =f 

/* and an |OPL segment *Y 
pO eee eS SH SSeS ee Scenes GaSe ae Seas */ 
Mwvoid main() 
ampesin 


int result; 


Myesult = readadc(); 


rintf('val=%d\n"', result}; /* 


end 
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/*read one value from the adc*/ 


i 


and print it out yd 
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SPECIFYING AN IOPL SEGMENT 
VY 


Thus far there is nothing particularly difficult about this process. We have | 
simply illustrated the calling of a simple assembly language function from’ 
C. The one significant difference in writing a program having a segment_) 
running at ring 2 is in the .DEF file. Here we must specify that the routine 
READADC is to run as an IOPL segment. This is done as follows: 


Y 
NAME ADPORT 
PROTMODE : Y 
SEGMENTS readadc TEXT CLASS 'CODE' IOPL ‘7. 


The PROTMODE statement specifies that the program will run in OS/2 
mode and the SEGMENTS statement lists any segments with special prop{_> 
erties: here the READADC segment is given IOPL privileges. Linking this 
in the usual way produces a running program that will allow you to access 
the ports and print out the value read from the A/D converter. The link 
command is | 


link @adport.1 /NOD; 
and the link command file is 


adport.obj readadc.ob j 
adport.exe 

adport.map 

llibce.1libt 

os2.lib 

adport.def 
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GAINING ACCESS TO THE PORTS 


While OS/2 1.2 does not require it, for upward compatibility your lOPI— 
segment routines should request access to the port numbers they plan to use 
This is done using the DosPortAccess call, which has the form 


DosPortAccess(0, access, firstport, lastport); 


where 


S©OOGeee 


}oe 


aie \ 


) 


0 

access 
firstport 
lastport 
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is a reserved short integer. 


is 0 to request access and | to release access. 
is the address of the first port you wish to address. 
is the address of the last port you wish to address. 


However, you must make this call directly from your IOPL segment, which 


»o¢O 


means it must be made in assembly language: 


EXTRN 


PORTLO 
PORTH | 


DosPortAccess:FAR 


YACCESSREO 
@yACCESSREL 


EQU 300h 
EQU 310h 
EQU 0 
EQU 1 


ao 
PUBLIC _readadc 


SZBAAAAALIT ITE TI 


_readadc 


push 
push 
push 
push 
call 


PROC FAR 
0 
ACCESSREQ 
PORTLO 
PORTH! 
DosPortAccess 


9 


. 
> 


9 


request access fo 
release access to 


reads adc 


reserved integer 
request access to 


request access to 
PORTLO-PORTH| 


port(s) 
port(s) 


port(s) 


ports 
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YA device driver contains a series of subroutines that control some device and 
emthat can be called from application programs. In OS/2, these drivers are res- 
ident programs that are installed when the system is initialized. You com- 
municate with them by opening the device by name. OS/2 returns a device 
handle that you can use to refer to the device until you close it. Device 
drivers run at ring 0 and do not need to be linked as IOPL segments or to 
ayrequest access to ports. 


Oo 
oTHE METRABYTE 8PGA CARD 


On this chapter we will write at device driver for the Metrabyte 
(nucDAS-8PGA card, where we set up the card so that it’ clock causes an 
qinterrupt each time it is to obtain a data point. This driver reserves a shared 
data segment where the data points accumulate and clears a semaphore 
when the total specified number of points has beena acquired. Then the 
calling program can read and store these points from that memory block. 
om The Metrabyte card we describe here is a low cost PS/2 card that can 
acquire data a point at a time on command or can acquire data at regular 
intervals based on a clock pulse and interrupt. The registers for this card 
start at the port base address (usually 0x300) and have the functions shown 
omn Table 23-1 


on 319 
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Table 23-1. Metrabyte 8PGA Registers 


Address Read Function Write Function 


Offset 
from Base 
oo 




















Read counter | Load counter | 
Read counter 2 Load counter 2 
Counter control 
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Reading Data Points 


There are several ways to acquire an array of data points from the 8PGA_) 
card and ones like it. 


WY 
1. Start a conversion and wait for the result. a, 
2. Have a clock start conversions and check for whether a conversion i 
done. 
3. Have a clock cause interrupts and start conversions when interrupts 


occur. a, 


Methods | and 2 require that your program “thang” waiting for a result, andw’ 
this wastes computing time unnecessarily. Instead, it is best to have data_) 
points acquired each time an interrupt occurs. As we have seen, you can ini; 
tiate a single 12-bit conversion by writing any value to port 0x301, and can 
check whether the conversion has been completed by checking bit 7 of tho 
status register. If bit 7 is set, the conversion has completed. Here, however_) 
we will use the clocks to trigger the ADC repetitively and acquire data af 
uniformly spaced time intervals. 


O6O¢ 


om 
o 
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Because the 8PGA board is designed to be flexible, yet inexpensive, you 
make some of the choices about how it is to be used by connecting pins on a 
jumper block connected to the rear connecter on the board. The most impor- 

~ tant pins on this connector are shown in Table 23-2. 


J 


) Table 23-2. Metrabyte 8PGA I/O Connector Pins 


Pin | Function 


N 


Fa 


Clock 0 input 


1s) 


Clock 0 output 
Clock | input 


Clock | output 


9964 


ON 


Clock 2 output 
19 | Analog channel 0 input (-) 
24 Interrupt input 


Analog channel 0 input (+) 


IO 


— 


Note that while there are several clock inputs and an interrupt input, there 
no pin to start an A/D conversion. Therefore, in our device driver we will 
yause an interrupt at regular intervals and start and A/D conversion by 
writing to port 0x301. At the next interrupt, we will read the result of the 
revious conversion and begin another. Other, more expensive A/D boards 
.rom a number of manufacturers, including Metrabyte, allow a clock to ini- 
ate an A/D conversion directly and cause an interrupt when the conversion 


ms complete. 
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The 8PGA Clocks 


There are 3 clocks in the 8PGA board, numbered 0, 1 and 2. The input oh 
clock 2 is permanently connected to a 1 MHz clock and by loading this 
counter with a value between 100 and 65535, you can get interrupts ever} 

100 microseconds down to every 65.5 milliseconds. While the A/D cap 

convert a data point every 35 usec, OS/2 cannot respond to interrupts much | 
faster than every 100 usec. If slower rates are necessary, you can cascadw/ 
together 2 or more of the clocks by connecting the output of clock 2 into th) 
input of clock 1, etc. a 
wy 
The Control and Status Registers YY 


The 8PGA board Control register selects which of 8 multiplexed analoy 
inputs is converted, and is used to turn on the board’s interrupt capability bl) 
setting the INTE flip-flop. You can read this same register (0x302) to fin? 
out if a conversion is in progress and whether an interrupt has been 

requested. The bits assignments are shown in Table 23-3. 


Table 23-3. Metrabyte 8PGA Control and Status Register 
Control (write) Status (read) 


1 = adc busy 0 = adc 
done 


MUX] MUX] 
MUX0 MUX0 





So | 
NHN | WwW 





ac 
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o™) Signals OP1 - OP4 are 4 digital output lines that you can set or clear and 
a Signals IP1 - IP3 are three digital input lines that you can read. The three 
MUX lines allow you to select 8 input channels from 000 to 111, and bit 7 
inidicates whether a conversion is in progress (1) or not (0). If you want the 
interrupt input from the connector to cause an interrupt, you must set bit 3 
of the control register, and you can see if an interrupt has been requested by 
reading bit 3. While you are processing an interrupt you should clear bit 3 


and reset it when you have finished. 
on 


parts OF A DEVICE DRIVER 


a Like any other program, there are two major sections to a device driver: the 

data area and the code area. Since device drivers have a specific format for 
| OS/2 to recognize them, the data area comes first, starting with an 11-word 
\(22-byte) header, followed by local constants, variables, and, if written in 
assembly language, a command table. 

The code area consists of three sections: the strategy routine, the inter- 
rupt service routine, and the driver initialization routine. Since the initializa- 
tion routine is called only when the driver is first loaded, it is placed at the 

Mend of the code segment so that its memory can be released when initializa- 
amtion is complete. 


a 
MEMORY MODELS 


Device drivers are generally written using the Small memory model: with a 
yingle code segment and a single data segment. While it is possible to write a 
endevice driver primarily in C, there are certain sections that must be written 

in assembly language. These include the interrupt service routine, the begin- 

aing of the strategy routine, and an interface to call the Dev_help subrou- 
Mine. In addition, it may be necessary to write parts of the initialization 
qmsoutine in assembly language, depending on the nature of the device. In our 

first example, we will write the entire driver in assembly language. We will 

illustrate how to write much of the driver in C in the following chapter. 
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THE DEVICE DRIVER HEADER 


The header for a device driver contains 22 bytes of information and MUST 


be the first data in the driver executable file. These data are as follows: / 
WY 
; device driver header bytes CC) 
point to next dw Offffh 
dw 1 ;32-bit -1 means loadable — 
device attr dw 8880h ‘device attribute bits ws 
of fst dw dcode:strategy ;offset to strat. routine, 
reserved dw -1 ;reserved 
dev_name db ‘device$ | -8-char device name WS 
res2 dw 4 dup (0) sreserved Y 
; local data storage starts here Nee 
; --saved at initialization time &) 
base address dw ? ;|/0 port base address | 
intrpt_ lvl dw ? ;interrupt level ed 
device help dd ? ;address of device help entry (| 
mbuf selector dw ? ;GDT selector slot 
Handle dw ? shandle returned on open Y 
bufsize dw ? ;size of acquisition buffer JU 
bufcnt dw ? ;count of acquire points ( ) 
bufhi dw 7 shigh address of buffer ped 
buf lo dw ? ;low address of buffer Y 
bufpnt dw ? ;pointer to current data pt (¢ ) 
wy 
sem hi dw ? shigh key to semaphore 
sem lo dw ? ; low key to semaphore WY 


point_to_next A pointer that will be linked to the next chained device 


driver. The 32-bit -1 means the driver is loadable. WV 

attributes The device attribute bits have the following meanings: Ww 
15 Set if this is a character device driver. Y 

14 Set if device driver participates in interdrivow 

communication. VU 

13 If character device, set for output until bus) ) 

support. If block device, set if non-IBM block 

format. oO 


eee 
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12 Set if file system sharing rules apply (character 
only). 

11 For character devices, if set the device must 
receive Open and Close commands. For block 
devices, if set the driver handles removable 


media. 

10 Unused. 

9-7 Function level, where 001 means OS/2 device 
driver. 

6-4 Unused. 

3 Clock device bit. If set the character device is the 


system clock device. 
If set, the character device is the NULL device. 
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1-0 For character devices, set bit 1 if this is the new 
stdout device and set bit 0 if this is the new stdin 
device. 

strategy This is the offset in bytes to the strategy routine entry 
( point. 

dev_name This is an 8-character ASCII character device name. 
oh IBM recommends that your device name end in a § sign. 
Am, For a block device, place the number of units in the first 
an byte. 


akollowing this data header, you should place all the variable and constant 
storage locations you will need for data storage while your driver is exe- 
suting. We will see later that we need to save the DevHelp routine address, 
nd we may need to save some device-dependent parameters as well. 


on 


“Wharacter and Block Devices 
om, 
Character devices are ones that have names like “LPT1:” and can have one 
4 more bytes of information sent to or received from them. Block devices 
ave names like ‘“‘d:” and are devices like disk drives. A character device is 
emot restricted to single characters and is the usual choice for data acquisition 
agards that process large “blocks” of data. 


eee 
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wy 
WY 
ww 
WwW 
THE STRATEGY ROUTINE ‘? 
The strategy routine is the “command interpreter” entry point for the device 
driver. All requests for the device pass through this routine and are dis) 
patched to various routines within the driver. Upon entry to the strateg) 

routine, the registers ES and BX point to a structure called a request packet 

The request packet has a variable length depending on what data is being 


passed to the driver, but always includes a, 
Packet struc WW 
PktLen db ? ; Length in bytes of packet Ly 
PktUnit db z ; Subunit number of block device | 
PktCmd db ? ; Command to device driver ww 
PktStatus dw ? ; Status word -status returns here 
PktDOSLink dd ? ; Reserved 

PktDevLink dd ? Device multiple-request link Y 
PktData db PktMax ae (7) ; Data words a, 
Packet ends & 


The most important byte in this packet is the PktCmd byte, which describe_) 
the action the driver is to take. The data words at the end vary depending 0; 
the action. 


Commands to the Strategy Routine 


€e¢ce 


The strategy routine must be able to process any commands it receives ar_ 
return errors for the ones that it cannot deal with. The most common com 


mands it receives are — 

Oh INIT Initialize the device. Sent when the driver 1, 

loaded. Y 

4 READ Wy 

6h INPUT STATUS & 
Th INPUT FLUSH | 

8h WRITE — 

Ah OUTPUT STATUS WY 

Bh OUTPUT FLUSH Ly) 

Dh OPEN i> 

Eh CLOSE = 

LY 

LU 

YS 

VU 


»699 


0h 
14h 
am 
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GENIOCTRL 
DEINSTALL 


In this chapter we will deal with INIT, OPEN, CLOSE, and 
GENIOCTRL. The remainder are discussed in the //O Subsystems and 
Device Drivers OS/2 manual. 


om 


Returning Status and Errors 


an, 


athe PktStatus byte of the request packet has the form: 
15 


i 
cm 


14 1is-— 10 9 8 y = Q 


If the driver detects an error, it must set bit 15, the error bit, and return an 
error code in bits 7-0. Bit 14 may be used by the driver for its own assigned 
neaning along with bit 15. Regardless of whether the driver detects an error 
“Mor completes the command successfully, it must set the Done bit. If this bit 
is not set, the driver may crash. If an error is detected, both the Done and 
Error bits are set, and bits 0-7 are set to the error code. The error codes that 
can be returned are 


om 

0 
Ox! 
omgx2 
a3 

0x4 
O>x5 
cmx6 
en x7 

Ux8 
x9 
OmYxA 


Write protect violation 

Unknown unit 

Device not ready 

Unknown command 

CRC error 

Bad drive request structure length 
Seek error 

Unknown media 

Sector not found 

Printer out of paper 

Write fault 

Read fault 

General failure 

Change disk 

Uncertain media (like in a close election?) 
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0x11 Character I/O call interrupted 
0x12 Monitors not supported 
0x13 Invalid parameter 


The errors you will most commonly return are 0x3, OxC, and 0x13. 


THE COMMAND DISPATCH TABLE 


ARETE TE 


The simplest way to check for legal commands is simply to set up ‘? 
command table starting at 0 (for the INIT command) and going up as higk 
as the largest number command you will process. For each command in the | 
list that you will process, simply indicate the address of the routine that thw 
program is to call. For each command you will not process, give the addres__ 
of an illegal command handler routine. You also need to have a maximur 
check to see that no command is greater than the maximum in the table. 

The example code in this chapter follows closely that provided in thw 


OS/2 Programmer’s Toolkit sample driver DEMODD.ASM. ey 
UY 
GN ep ae et ee ame feet Og Ga aha ted repent! Og ye tea Te eT , 
: Command table for commands to driver | 
WS 
last command equ 16 ;Command codes >16 are illegal\__ 
command table dw INIT 50 calls INIT Subroutine ‘i> 
dw BAD ‘| to / are Y 
dw BAD ;not supported WY 
dw BAD .3 | 
dw BAD 4 = 
dw BAD 55 UO 
dw BAD °6 + 
dw BAD +7 . 
dw BAD ;8 calls WRITE subroutine “~~ 
dw BAD 39 iS unsupported , 
dw BAD >10 calls STATUS Subroutine _, 
dw FLUSH -11 calls FLUSH Subroutine Y 
dw BAD ;12 is unsupported a, 
dw OPEN 313 calls OPEN Subroutine i> 
dw CLOSE 14 calls CLOSE Subroutine Y 
dw BAD 315 is unsupported WS 
Ww 
WY 
ww 
ww 
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dw GENIOCTL ;16 calls GENIOCTL Subroutine 


58999 


>. 


Then, interpreting the command table amounts to simply calculating the 
offset from 0 to the command in words, doubling to make the byte offset and 
naking a near call to the address pointed to. 


Oe gig es a ee re pt pes ee 
CORROR BIT equ  8000h ;Word indicating error 
DONE BIT equ 0100h ;Bit indicating command done 


GENERAL FAILURE equ  0O00ch ;General failure error code 
(OVNKNOWN COMMAND equ  0003h ;Unknown command error code 
aay NVALTD_PARAMETER equ 0013h ;invalid parameter code 


O STRATEGY PROC FAR 
am The code below calls the appropriate subroutine based 
;on the call table in the data segment 


(™, mov al,byte ptr es:[bx].PktCmd ;get command code 
cmp al, last command ;|s this one in range? 

( ja UNSUPPORTED ;no, go to error routine 
™  cbw ;convert byte in al to word 
am mov di ,ax smove it to di 

: sh] dig! smultiply by 2 for bytes 
@ call word ptr command table[di] ;and call routine 
m or  es:[bx].PktStatus, DONE BIT ;set done bit 
Ps ret sand exit 
eM™NSUPPORTED: 

call BAD ;command is not supported 

ab ret 
‘a 
vay TRATEGY ENDP 
AD PROC NEAR ;set error bit and unknown command code 
am mov es:[bx].PktStatus, ERROR BIT + UNKNOWN COMMAND 

ret 
ap ENDP 
/ | aiatetatatatetatatatatatatatatatateiatatatatatatatatatetstetatetsteisienstatatenatataaiaenaaaaeaaaataats 


(Nhe BAD subroutine simply sets the error bit and the unknown command 
astror code and returns. The UNSUPPORTED label is used so that a call to 


fy 
am 


r | 


_ 


C 
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5O @« 


the BAD routine can be made from both places. If a match is found, on th 
other hand, the routine pointed to by 


. 


command table[di | 


is called and, upon exit, the command interpreter sets the DONE bit. 


INITIALIZING THE DEVICE DRIVER 


60000 < 


When the OS/2 system is loaded at power-up or bootstrap time, the OS/ Ioad 
scans the CONFIG.SYS file and loads any device drivers whose names ars) 
specified using the DEVICE= statement in that file. When the drivers are) 
loaded, they are sent an INIT command packet containing the following 


information: Y 
InitPacket Struc bod 
IPktLen db 24 ; Length in bytes of packet WY 
IPktUnit db 2? 3 Subunit number of block device &y 
IPktCmd db 2? 3; Command to device driver 
IPktStatus dw ? 3 Status word -status returns here Y 
IPktDOSLink dd ? 3; Reserved Wy 
IPktDevLink dd ? 3 Device multiple-request link 

InitDatal db 2? 3 return number of devices here sal 
InitPtr] dd 2? 3 pointer to DevHIp entry point WJ 
InitPtr2 dd ? 3; pointer to INIT arguments ) 
InitData2 db ? 3; driver num for first block dev unit haa 
InitPacket ends WwW 


Note that the first 13 bytes are just like the request packet described above’ 
The only difference is the assignment of the bytes after the first 13. Th 
most important argument here is InitPtr1, which contains the address of th 
DeviceHIp routine. This routine can be used to request a number of compley 

system services such as registering interrupts and requesting a memory 
buffer that can be accessible to both the driver and the user’s callinyv 
program. The other argument you may choose to process is InitPtr2 whiq 

points to the string of arguments that can be passed after the DEVICE> 
command in the CONFIG.SYS file. The interpretation of this string 1S” 
entirely up to you. 


86000006 
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ALT 


The minimum that you must do, then, when processing the INIT 
ommand is to save the address of the DevHelp routine in your driver’s data 


a 


segment. This can be done by the following simple code: 


O)nd oF coDE equ $ sdefine last used location 


mov ax, word ptr es:[bx].InitPtr1 
anmov word ptr device hlp, ax 


” Save the second word of the pointer to the DevHIp routine 


om ae ee ee 


mov ax, word ptr es:[bx].InitPtr1+2 
_mov word ptr device hlpt2, ax 
Om; : 
ap’ 
pon returning from the INIT command, you must set the value of the 
ointer following the basic request packet to contain the 16-bit offset to the 
“nd of the code and the 16-bit offset to the end of the data segment. You 
ust also set the second long pointer to zero for character devices. Since the 
CSNIT routine is called only once during the life of your device driver, it is not 
nreasonable to release that memory after the code is executed. You do this 
| vy returning in InitPtr1 the word offset to the end of the code segment. You 
snerally put the INIT code last in your device driver and return the offset 
«™) the location where INIT starts so that memory can be reused. 


( Set done bit to show that initialization is done 
ampmov es:[bx].PktStatus, DONE BIT 


Mropy end of code address to request packet 
emea ax, END OF CODE 
“mov word ptr es:[bx].InitpEnd, ax 


O™opy end of data segment to request packet 
lea ax, END OF DATA 


»ooo 
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mov word ptr es:[bx].InitpEnd+2, ax 


xOr aX, ax ;set ax to 0 

mov word ptr es:[bx].InitpEnd+4,ax ;zero out 2nd pointer 
mov word ptr es:[bx].InitpEnd+6,ax_ ; 

ret 


INTERROGATING THE PROGRAMMABLE OPTIONS 


6600008000 6€ 


All PS/2’s running on the Microchannel architecture allow the user to con 
figure the boards’ I/O port addresses and interrupt levels by software 
command. This obviously makes the system more flexible when a number od 
different kinds of cards are present in a system. However, it does mean tha_ 
you cannot be sure that the board in your system will respond to the sam 
I/O ports and interrupt levels as in another system. For you to find out how 
the boards are configured, each has been assigned a unique id number. ad 
you know the id number of the board, you can search each slot for it and, \__ 
it is found, ask it how it is configured. 
To make this query, you start by interrogating slots 8 - 15 for board id’s 
If your board id is 0x6029, you start by sending the slot number to port 0x90 
and then read the low byte of the board id from port 100. If it matches, yO 
check the id of the upper byte from port 101. If that matches, you begi_ ) 
querying the board-specific parameters from ports 102, 103, and higher a* 
specified in the board documentation. In the case of the Metrabyt 
ucDAS-8PGA board, port 0x102 returns a byte containing the lower bits wY 
the port base address, interrupt level, and whether the board is current|_) 


¢ 


enabled: 


YU 
7-5 port base address, bits 7-5 Se 
4-1 interrupt level | 
0 board is enabled if this bit is 1. _ 


Port 0x103 contains the upper byte of the base port address. We refer to the” 
“base address” because such boards usually use a block of I/O ports startirie” 
at a defined base address. In the case of the ucDAS-8PGA card, eigi_) 
sequential ports are used. After querying the board’s I/O port base addrey 
and interrupt level, you should save them in the driver’s data area so you can 
use them when the driver is asked to access the board. 


©eeode 
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©THE DEVICE HELP ROUTINE 


{he DeviceHIp routine is a system routine you can call with a series of argu- 

nents to access OS/2 system services. OS/2 version 1.2 defines 38 such 
(%ervice routines that you may access. We list the most common ones in 
amable 23-4 All of these functions are called with arguments in the registers 
a return with results in the registers. 


‘ai 
VIRTUAL AND PHYSICAL ADDRESSES 


O: protected mode OS/2 does not refer to addresses directly. Instead, the 
Orgment registers are loaded with selectors from a descriptor table. These 

electors point to either a local descriptor table (LDT) or a global descriptor 

cable (GDT), which in turn contains the offsets of the actual physical 
dresses. The purpose of this is to allow memory protection and the move- 
@™ment of data in physical memory during memory management without 
aequiring a change in the addressing of the program. An address constructed 

vf a selector and an offset is referred to as a virtual address since the actual 
dress calculation is performed by the hardware. In real mode, however, 
(™e segment registers do contain the addresses of actual segments in 
anemory, and these are referred to as physical addresses. 

A number of the functions provided as DevHelp calls allow you to 
\4anipulate memory address representations between physical and virtual 
(dresses, so you can use physical addresses for hardware-dependent func- 
cons such as DMA buffers and virtual addresses to refer to the locations in 
ag ciected mode. The other implication of these functions is the ability to run 

1 OS/2-style device driver in DOS mode. This is provided primarily for 
mpatibility and is of little interest to new program development and will 
emt be covered in detail here. 


a 
OESERVING A MEMORY BUFFER 


om 

:. number of kinds of cards that you may write device drivers for are used to 
quire data of some sort into a table or memory buffer. These data may be 
o™mples from an analog-to-digital converter or characters from some com- 
ARunication device. In either case, you will need a memory buffer where you 
Pale 

om 

on 


ee) 
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Table 23-4. Common Device Help Calls , 
SemRequest le | Claim a semaphore Y 
SemClear Clear a semaphore ps 
Ww 
SemHandle Get a semaphore handle s 
PhysToVirt Ox15 Convert physical to virtual ‘> 
address | 
WY 
VirtToPhys 0x16 Convert virtual to physical | 
Ww 
address } 
| Ww 
PhysToUVirt Ox17 Convert physical to user virtual © 
address | 


( 


AllocPhys 


0x2D Allocate GDT descriptors | 


FreePhys 
SetIRQ 


© @<¢ 


UnSetIRQ 
AllocGDTSelector 


686088606 


PhysToGDTSelector Ox2E Convert physical to virtual GDT ps 
address ed 

RealToProt Ox2F Switch from real-to protected ee 
mode 

ProtToReal 0x30 Switch from protected to real - 
mode | 

EOI 0x31 Issue an End of Interrupt 


UnPhysToVirt 0x32 Mark PhysToVirt complete 


ABIOSCall 0x36 Invoke advanced BIOS function 
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can store these data and pass the array back to the calling program. While 
the acquisition of these data is a topic to be discussed as part of GenIOCtr1 
functions, you must reserve the place in the Global Descriptor Table (GDT) 
at initialization time. Note that you do not actually reserve any memory yet, 
but only a place in the descriptor table. 


; reserve one GD] selector - offset:left in mbuf_ selector 
am; symbols are defined in this file: 


@i nciude driver. inc 
ey rere ey eee 
push ds scopy GDT selector into es 
pop es ;es contains GDT selector 
O™ov di, offset mbuf sel ;offset to this data location 
anno cx. | ;number to reserve 
~-mOv d|l, DevHIp AllocGDTSel ;number of function 
O:all [device help] scall function 
anic intt err serror (fF carry set 
a, 


ol HE OPEN COMMAND 


Oo. OPEN command is really intended primarily for file I/O handling, so 

hat future commands to that file need not carry so much information 

emegarding filename and location. It is also possible to use the OPEN 
command as a check to make sure that your device isn’t in use by another 
cask and to set up interrupt processing closer to the time that you will need 

Mo use it. 

o) The OPEN command is passed to the driver when you make a DosOpen 


all from your main program. This has the form 
ak 


emosOpen(szDevName, &handle, &action, IL, 
attr, openflag, openmode, OL); 


om, 

where 

szDevName is a string containing the device’s name, such as 
ped “pgas$.” 

ok handle is the location where the device handle is returned. 


yous 
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& action 


1L 
attr 


openflag 


openmode 


returns | if the file exists, 2 if it was created, and 3 1 
replaced. For a device, this should always return 1. 


is the file size, and any value will do. 


is the file attribute word. Should be 0 for a device. 


000060006 


specifies the action to take if the “‘file”’ exists. 


xxxx0000 fail if file exists 

xxxx0001 open file if it exists 
xxxx0010 replace file if it exists 
0000xxxx fail if file does not exist 
0001xxxx create file if it does not exist 


The correct value for opening a device is 0x01. 
This is a 16-bit word whose flag bits are set as 
DWF xxxxx1SSSxAAA 


where 


©8OOOOOSE 


D D=0 means open normal file, D=1 means this KY 
a block device. 

W Writes to the file through the system buffer 
cache if this is 0, and if | the actual physicas/ 
write is performed before the write call returns. (_) 


I Inheritance flag. If 0 the file handle is inheritec 
from a calling process, if | the file handle is 
private. — 


F If O, errors are reported to the system errd_) 
handler, and if |, errors are returned to the calle 
by a return code. 

S Sharing mode. Defines action other processes” 
can take with this file/device: 

001 deny read-write access 

010 deny write access 

011 deny read access 

100 allow read and write access 
X reserved. 


8060060000 ¢ 
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L reserved. 


»26S899 


Receiving the OPEN Command 


When an open command is passed to your device driver, OS/2 has already 
-ssigned a device handle to this call to the device. This handle is in the first 
Omata byte after the packet. You need only check to see that the device cur- 
ayently is not in use and save the handle to indicate that it is now in use. 


@MOPEN PROC NEAR 


test Handle, OffffH ;see if handle is currently Q 
ob jne open err ;device already opened! 
MM) mov ax, word ptr es:[bx].PktData ;get file handle 
a mov Handle, ax ;save locally 
ab 


REGISTERING AN INTERRUPT 


Dne common task that may be performed at Open time is telling OS/2 that 
your device will expect interrupts on a given level and want to have those 
apinterrupts sent to a particular interrupt service routine. You already know 
the interrupt priority level from the INIT command, where it was either set 
vermanently or interrogated from the POS routine. The SetIRQ call is used 
(o register the fact that this device can now generate interrupts. The argu- 
ents include the request level, whether the interrupt can be shared, and the 
address of the interrupt handler. Note that bx is used and must be saved 
and restored: 


push bx ;save bx 

mov ax, OFFSET cs: inthandler saddress of handler, 
mov bx, Intrpr. Iv! ;interrupt request 3 
mov dh, O ;dis-allow sharing 
mov dl, DevHIp SetIRQ ;device help func # 
CALL [device hlp] sca!) if 

jc Open err serror if carry set 
pop bx srestore bx 

mov es:[bx].PktStatus, DONE BIT sand set done bit 
ret 


POVSISseeeosoS 
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THE INTERRUPT HANDLER 


When an interrupt occurs, it is intercepted by the OS/2 kernel, and all the 
registers are saved. Then your interrupt service routine is called by a far call_D 
and you must return using a far return. Your service routine does not neeq ) 
to save or restore any registers. 

The main strategy of an interrupt service routine is to respond to the” 
interrupt as quickly as possible, obtain the data point, and return to thi 
interrupted program. If you have set up your device to allow interrup/ ) 
sharing, then you must be sure that this interrupt is from your device. If it is 
not from your device, you should return from the interrupt as quickly as pos- 
sible with carry set, so that OS/2 can continue polling other devices on tha\v 
level. If it is from your device, you should process the interrupt as quickly a) 
possible and return with carry clear. Note that you return from the service 
routine with a RET instruction, since the final interrupt handling is carried 
out by OS/2. VY 

The interrupt service routine that follows is for acquiring an array o_| 
data points from the 8PGA board: one each time the clock ticks. When th 
total number specified is collected, the interrupt flag on the board is disa- 
bled, and a semaphore is sent to the calling program indicating that the data 


are collected. a, 
ee v 
: Interrupt Handler Ly 


; In the 8PGA ADC board, interrupts are caused by the clock 
; and the ADC must be started manually. In order to do 

; this efficiently the handler reads the ready ADC value 
; and starts the next conversion going thereafter. 


Ne ee) 


INTHANDLER PROC FAR 


mov dx, ade status ;see if this belongs to us 
in al, dx ;check status bit 

test al, 8h ;if high it is ours 

jne int ours ,yes IL is 

stc ;this says it is NOT ours 
ret sexit to Colonel 


;interrupt is ours, process it ASAP 
int ours: 


©6000 0008 O08 é 


mov 
xor 
out 
mov 
mov 
call 
add 
mov 
out 


we 


we 


MOV 


in 
mov 
dec 
in 
shr 
mov 


out 


rer 
ite 


79 9993939999393909999999999 


mov 
cal] 


J 


protmode: 

mov 
mov 
mov 
mov 
add 
mov 
mov 
dec 
mov 


jg 


XOr 


PSSST sSsSsSsosoSosSS 


push 


dx, 


;store current data 
smSw 
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dx, adc status 

al, al 

dx, al ;disable interrupt flag 
ax, int_level ;set interrupt level 


;official way to send EOI 
;send EOI to intrpt ctrir 


dl, DevHIp E0I 
[device hlp] 


ax, 060h sadd spec EO! bits for 8259 
dx, O20h 
a | ;set int levl spec EOI 
dx, adc hibyte ;don't bother to 

scheck status bit 
al, dx 
ah, al spUE Tf in High Bit 
dx ;address of lower byte port 
al, dx ;get lower byte 
ax, 4 sshift to 12 bits 
dx, adc hibyte j;writing to port 

;Starts next conversion 
dx, al ;contents unimportant 

point in buffer 

bx ;get machine status word 
bx scopy it onto stack 
bX, 1 ;puts processor state in cf 
protmode ;already in protect mode 
dl, DevHlp RealToProt ;else switch 
[device hlp] 


bx, mbuf selector ;get GDT selector 


;turn off ADC now 


es, bx sand set as es seelctor 
bx, bufpnt ;get buffer pointer 
es:[bx], ax ;store data point 

DR, 2 ;increment buf pointer 
bufpnt, bx sand restore 

cx, bufcnt >see if we re done 

Cx ;decrement counter 
DuUTcNE, €x ;put it back 

intexit ;i1f not continue 

al, al ;set ax=0 
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mov cx, ade Status ;5fo0p getting points 

out dx, al ;INTE flop is disabled 
;send the main program a semaphore that the data is done 

mov ax,sem hi 

mov bx,sem_ lo 

mov d1,DevHIp SemClear 

cal] device hlp 
; now release semaphore 

mov ax,sem hi 

mov bx,sem_ lo 

mov dh ,0 snot in use 

mov dl ,DevH|p SemHandle 

call device hlp 


intexit: 


jmp intdone 


mov ax, mux value ;select mux and INTE flag 
add ax, IREQ Dit 

mov ax, acc status 

out dx, al sturn INTE on in 8PGA 


;restore interrupts and exit 


intdone: 


protex: 


sti ;turn interrupt on 

pop ax ;restore processor status 
rer ax, | ;check protected mode 

jc protex eves, do nothing 
mov dl, DevHIp ProtToReal ;no, put it back 
call [device hlp] 

cle ;interrupt was Ours 

ret sand exit 


INTHANDLER ENDP 
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Sending an End of Interrupt to the Controller 


An of the PC’s and PS/2’s use an 8259 interrupt controller chip that must 
be reset as soon as you are sure that you are acknowledging your own inter- 

O™wrupt. This allows interrupts to continue to occur at the same or higher 

anlevels. If you are sharing interrupts with other devices on the same level, 
you must use the DevHIp call to reset the interrupt controller: 


o mov ax, intrpt_Ivl ;get interrupt level 
mov dl, DevHIp EO! j;get function number 
OW call [device hlp] ;send EO! to interrupt controller 


Om your interrupt is not shared, you can usually manipulate the controller 
omchip yourself by sending 0x60 plus the interrupt level number to port 0x20. 


\ mov ax, int level sSec interrupt. level 

a add ax, 060h sadd spec EO! bits for 8259 
mov dx, O20h ;send this to 10 port 0x20 

OY) out dx, a! ;set int levl spec EOI 


Ownile this is some 80 microseconds faster than making the call to DevHIp, it 
os not technically recommended for multitasking systems and cannot be used 
when an interrupt level is shared. 


am, 


@Real versus Protected Mode 


Mr the interrupt is yours, you must be sure that the cpu is running in pro- 
ected mode before trying to address the data array using the global 
amescriptor table and offset. To do this you use the SMSW instruction to copy 
the machine status word into a register. If bit 0 is one, the processor is 
.unning in protected mode, and if it is zero, the processor is running in real 
node. If the processor is indeed in real mode, you must call the DevHelp 
q@unction to switch it to protected mode before getting the data point. You 
agnust also restore the processor to its original mode when you are finished: 


ap Smsw bx ;get machine status word 
push bx scopy it onto stack 
rer bx, 1 ;puts processor state into carry 


jc protmode ;already in protect mode 
mov dl, DevHIp RealToProt ;else switch into protect mode 


7SoS9 
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Changing machine states is very slow on 80286 machines, which must essen- 
tially be “rebooted,” but quite fast on 80386 and later machines. If your 
OS/2 machine has an 80286 microprocessor, modify your CONFIG.SYSw’ 
file to include the statement 


-_— 


Ww 
PROTECTONLY=YES LW 


This will prevent the “DOS box” from appearing, and the machine will run 


only in protected mode. uJ 
a, 
Processing the Interrupt VW 


Once you are in the correct mode, you can address the data buffer using the 
selector allocated at INIT time and loaded at ADCGO time. The offset into 
the buffer must be stored locally in the data segment and loaded into anw 
index register. Then, it must be incremented and re-stored and the counte: 
decremented. If the number of data points is not completed, you simply exit 
with a RET instruction. If it is, you turn off whatever continues to cause the 


interrupt. WY 

protmode: Y 
mov bx, mbuf selector sget GDI selector J 
mov es, bx sand set as es selector 
mov bx, bufpnt ;get buffer pointer heactd 
mov es:[bx], ax ;store data point 7 
add bx, 2 ;increment buf pointer | 
mov bufpnt, bx ;and restore po 
mov cx, bufcnt >see if we're done VW 
dec cx ;decrement counter iJ 
mov bufcnt, cx ;put it back 
jle intstop ;if not continue getting points \ 
mov ax, mux value ;select mux and INTE flag _, 
add ax, IREQ bit ;re-enable interrupt to board 
mov dx, adc status Y 
out dx, al sturn INTE on in 8PGA a, 

srestore interrupts and exit 6) 
sti ;turn interrupt on bd 
pop ax ;restore processor status sw 
rcr ax, | ;see if it was in protect mode | 
jc protex syes, do nothing 
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mov dl, DevHIp ProtToReal ;no, put it back 
call [device hlp] 


29989 


Orotex: 

lain ele ;interrupt was ours 
ret sand exit 

OYNTHANDLER ENDP 

on 

OTHE GENIOCTRL COMMANDS 

an 


am he generic I/O control command category is intended to be used to com- 
municate any special type of information specific to the device. For 
-xample, you could set timing parameters, data rates, numbers of data 

oints, and multiplexer information using these commands. You also use one 

anf these commands to actually begin data acquisition or other communi- 
cation with the board. 


(" The function call from C has the form 


vosDevl0CtI( édata, &parms, function, category, handle); 


where 
o" 
a data is a long pointer to a structure that will receive data from the 
call. 
on 


afk parms is a long pointer to a structure that will send data to the device. 
qfunction is a function code, usually 11 for general I/O commands. 
o™ategory is the category within the function. 

yhndle is the device handle returned by the DosOpen call. 


‘ab When a GenlOCtrl command is received by the driver, the structure 
yinted to by ES:BX has the form 


Oy 0Packet Struc 
aepktLlen db 20 ; Length in bytes of packet 
aPktUnit db ; Subunit number of block device 
PktCmd db ; Command to device driver 
oyektStatus dw ; Status word -status returns here 
iPktDOSLink dd ; Reserved 
PktDevLink dd ; Device multiple-request link 


YN VY VN VY VY 


“™ 
em 
( 
am 


344 WRITING DEVICE DRIVERS 


006000006 


GIlOCategory db ? ; function category 
G!0Code db ? > function code 

G!OParm dd ? ; pointer to parameters 
GlOData dd ? ; pointer to data returned 
GlOSysFile dw  ? ; System file number 
G|OPacket ends 


The function categories and codes have been defined so that only some art 
available for your use. Categories 1-11 have specific meanings, and categor(_) 
11 has been defined as General Device Control. Within the category, onl; 
codes 1, 2, and 0x60 have been defined: 


YY 
1 Flush input buffer 
2 Flush output buffer Y 
0x60 Query monitor support WY 


As before, you must respond to each command by either processing it ow 
returning an error. If your device driver does not support device monitors, 4.) 
few data acquisition cards would, you must return the error 0x12: no mon\_) 
tors supported. 

While it might appear that you can use any function codes under cate 
gory 11 that you wish, it turns out that individual bits of the function codw 


have special definitions: Ly) 
VW 

Bit Meaning &) 
7 0 - return error if unsupported; | - ignore error. , 
6 0 - intercepted by OS/2; | - passed to driver. a, 
5 0 - sends data and commands to device; | - queries data and informa” 
tion from device. WY 


The state of bit 5 is merely a convention, but you must set bit 6 to 1 in ordwwy 
for your function command to be passed to the driver from the calliy 

program. Therefore, all user-defined function codes must have bit 6 se” 
(0x40). 
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>see 


omDefining Commands to GenlOCtrl 


Ov ou can use any of these commands with bit 6 set to perform any device 

Specific tasks you wish to define. You can pass arguments to the call by 

amsetting the pointer & parms to point to a structure containing any values you 

aneed to use to set up your device. Likewise, the driver can return any data 
values in a structure pointed to by & data. 


om 
interpreting GenlOCtrl Commands 


omVhe easiest way to detect which of several GenIOCtrl commands has been 
agent is to scan another table just like the main command table. For a data 
acquisition card, this table might include 


Command table for Generic!lOCtl commands 
‘ah -- all have bit 6 set 


e™MinFuncCode equ 4Oh 
even 

aenCmdTable label word 
om dw offset SetClock >40h 
a, dw offset SetGain sAth 

dw offset ADCGo >h2h 

” dw offset SetMux ;43h 
a dw offset GetCount s44h 
OPndGencmdTab le equ S-GenCmdTable 

:hen this table can be used to call the correct subroutine by 
a 
OENIOCTL PROC NEAR 
am mov al, es:[bx].Gl0Category ;get the category 

mov ah, es:[bx].G!0Func ;put fn and cat in ah-al 

@ «mp es:[bx].GlO0Category, GENDEV ;genl device 10 CtrJ 
am je GenCategor yOK ;category ok, go on 

,|f not allowable category, set the error bit 
en l0Ct 1Bad: 
a or es:[bx].PktStatus, ERR BIT + UNKNOWN COMMAND ; 

ret sand exit 


ik, 
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GenCategory0OK: ;Verify range of Function Code 
xor ah,ah ;set ah = 0 
mov al,es:[bx].GlOFunction 5;Get fn code from packet 
sub al ,MinFuncCode sMake rel. to table start 
j| Genl0CtIBad silklegal if <0 
sh] ax, | ;convert to table offset 
cmp ax,EndGenCmdTable ;Beyond end of table ? 
jae Gen!lO0CtIBad ;yes, error 
mov di,ax ;Save table offset 
call word ptr GenCmdTable.[di] ;and call routine 
ret ;exit 


BEGINNING DATA ACQUISITION 


SOOOSSOCOOCCCCaC 


Interrupt-driven data acquisition presents two special problems unlike thos) 
found in classical interface cards. Since data may be arriving at a fairly hig/ 
rate of speed, you need to be able to store it without waiting for the maip 
program to respond. Therefore there must be a memory region where thes” 
data can be stored that is accessible to both the device driver and the callin.) 
program. Second, such data usually arrive in bursts or scans, followed by LY 
pause sufficient to process or store the data. Therefore the calling program 
must have some way of discovering when the scan is complete so that it cate 


move the data from the buffer to long-term storage elsewhere. a, 
WY 
Allocating a Memory Buffer WY 
iJ 


Since the data will arrive under interrupt control, the device driver mus* 
allocate the memory and then pass the address of that memory to the user 
calling routine. This takes place in the following steps: WY 


1. Fetch the desired memory size. Y 
2. Allocate physical memory. a, 
3. Convert this memory address to a GDT selector for the driver. 
4. Convert the memory address to a user selector. Pass the pointer back te 


the user. 
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Let us assume that the number of points to acquire is sent to the driver as 
apart of the parameter structure, along with a pointer to a semaphore handle. 


a struct ADCParms 


begin 
int point_count; /* number of data points */ 
on unsigned long far “sem; /* semaphore handle a 
end adcp; 
a P 


ant hen we can access these parameters by making DS-SI point to the struc- 
(ure: 


ush ds sthis is destroyed right here 
ids si, es:[bx].Gl0Parm ;pointer to parameters 
Mov cx, ds:word ptr [si]  ;count of points to acquire 
ameov bx, ds:word ptr [sit+2];high sem handle 
| ;bx is lost here 
Mov ax, ds:word ptr [sit+4]; low sem handle 
amop ds shere we put ds back 
mMOv bufcnt, cx ;Save count 


Ve then allocate physical memory using the DevHlp call AllocPhys. This 
as the parameters 


ax:bx size of data area in bytes. 


2 


If 0, look above | meg boundary, if 1 look below | meg. 


Value of AllocPhys function code. 


mov bx, bufcnt 
sh] bx, 1 
mov ax, O 
mov an, 0 


mov 
cal] 
jnc 


[device hlp] 
gotsome 


mov bx, BUFSIZE 
mov ax, 0 
mov dh, 1 


mov 


99299999999000aa 


; aS a last resort, try below 1 


;set size 

-*2 for bytes 
shigh part of size 
; look above 1 meg 


dl, DevHIp AllocPhys 


;al locate memory 
;OK if carry clear 


meg 
;set size 

shigh part of size 
; look below 1 meg 


dl, DevHIp AllocPhys 
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cal] [device hlp] ;allocate memory 
jnc ADC Err ;give up if no bufs 
; available 


gotsome: 
mov bufhi, ax ;save physical address 
mov buflo, bx sreturned in ax:bx 


6000000000 t 


Setting a GDT Selector 


Recall that we allocated a GDT selector at initialization time, so that we 
could use it to point to memory that we will be using in data acquisition. WW 
now need to take the physical address of the memory buffer we just allo.) 
cated and convert it to a GDT selector. Then we can quickly respond te 

acquisition requirements at interrupt time. This is done using thé , 


PhysToGDTSelector function. VY 

;convert physical address of buffer to GDT Y 
mov ax, bufhi ;get physical address WS 
mov bx, buflo shigh and low words 
mov cx, bufsize ;set the size needed Y 
mov si, mbuf selector ;here is where it is returned\ y 
mov dl, DevHlp PhysToGDTSelector 
call [device hlp] snow the GDT points to ari aed 


jc ADC Err ;else deep yogurt 


WY 
Y/ 
Converting Buffer Address to a User Virtual Address Y 
WY 


We also need to represent the buffer address such that the user can get @” 
the buffer. This is done by converting this same address to one that th 
user’s local descriptor table (LDT) can access: 


push es ;Save es:bx, destroyed by cal] 
push bx 

mov ax ,bufhi ;get physical addresses again 
mov bx,buf lo 

mov cx, bufsize sand size 

mov dh, 1 ;segment read/writable 

mov d1,DevHIp PhysToUVirt 
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call device hlp ;convert for user 
ic ADC Err ; error if can't convert 
; now supply the user with the virtual address 
Oyhysi: 
a, mov ax,es ;answer returned in es:bx 
| mov cx ,bx ;copy to ax:cx 
on pop bx ;restore ptrs to packet 
Mm Pop es ;restore both again here 
push ds ;and save ds 
O Ids si, es:[bx].GlO0Data ;get address of data 
mM mov ds:word ptr [si],cx ;copy address descriptor in 
mov ds:word ptr [sit2],ax 
‘a pop ds ;restore ds again 
‘ai, 
a, 


~ fELLING THE CALLING PROGRAM THAT 
XCQUISITION IS DONE 


2 


aw hen we start data acquisition, we pass the device driver a number of points 
.o acquire, and the pointer to a semaphore handle that we will set, and wait 
) have cleared, indicating that one scan is completed. 


on 
(m unsigned long far *SemHandle; /* system Semaphore */ 
“ set up a semaphore to see when scan is done “/ 

psCreateSem((USHORT)1, /*not exclusive ownership*/ 
(PHSYSSEM)&SemHandle, /“location of handle a 
''\\SEM\\ADDONE .ADC"’) ; /*name of semaphore ar 
Os SemSet (SemHandle); /*set the semaphore ai 
andcp.point_count = 200; /*take 200 points st 
adcp.semhandle = SemHandle; /*pass semaphore handle “*/ 
/* to driver * / 

on 
Aosdevl0Ct1((PVOID)Edataword, /*start ADC for 200 pts */ 


(PVOID)&adcp, ADCGO, 
an Devicel0, handle); 


vosSemWait(SemHandle, 32768L); /“wait for semaphore to clr*/ 


sCloseSem(SemHandle); /*then delete it “J 


»@es 
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Clearing the Semaphore from the Driver 


Recall that we save the pointer to the semaphore when we saved the number 
of data points above. Since we are operating in a different protection ring_/ 
and using different descriptor tables in the driver, we must convert the ) 
address of the semaphore to a semaphore key we can use within the driver: 


YW 
;remainder of call at start of ADCGO - get semaphore handle 
mMOv bx,ds:word ptr [sit2] shigh sem handle Y 
;--bx is lost here a, 
mov ax,ds:word ptr [sit4] ; low sem handle | 
YZ 
pop ds shere we put ds back 
mov bufcnt, cx ;Save count WwW 
;convert to semaphore key usable by driver CY 
--returns in ax-bx(bx is lost) 
mov dh, 1 ;semaphore in use Y 
mov d1,DevHIp_ SemHandle WS 
cal | device hlp ;converts to semaphore key 
mov sem hi ,ax ;save system key" | 
mov sem_ 1o,bx VW 


Then, when acquisition is complete, you simply clear that semaphore using 
the analogous DevHIp call, and then release the semaphore: 


;send the main program a semaphore 
;indicating that the data are gathered 


mov ax,sem hi ;get the semaphore key 
mov bx,sem_ lo ;from local storage 
mov d1,DevHIp_ SemC lear ;clear it 
call device hlp 

; now release semaphore 
mov ax,sem hi >reload ax and bx 
mov bx,sem_lo swith the semaphore key 
mov dh ,O >indicate release it 
mov d1,DevHIp_ SemHandle 
call device hlp 


SOOO OOOOOOOOOOO OE 
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ASSEMBLING AND LINKING YOUR DEVICE DRIVER 


The assembly process is completely straightforward: simply use the MASM 
assembler to assemble the driver. Then link it as 


»® 


link aiodrvr.obj,aiodrvr.sys,aiodrvr.map/map, \ 
os2.lib,aiodrvr.def; 


Io 


Where the .DEF file contains the following: 


ab we PN 
WNIN AN GN Sat ae at 


Module Definition File for the Device Driver 


ILO 


am IBRARY AIODRVR ;specifies AIODRVR as dynamic link module 
PROTMODE ;Runs only in protect mode 

@oneE  PRELOAD =; Device driver - preload 

eOyATA PRELOAD ;Device driver - preload 


8009808080888 98GOOGSSO 
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Since much of the job of a device driver is interpreting commands and 
qgalling the appropriate routine, it seems as if it might be unnecessary to 

write the entire driver in assembly language. It is in fact possible to write 
\_nost of a device driver in the C language with only a small assembly lan- 
)uage wrapper program that remains unchanged from one driver to the 


angext. 
‘a, 
COVERALL C-DRIVER STRATEGY 


gust aS we wrote our assembly language driver in the small model, where 
were is only one code and one data segment, we will do the same in the C 
q™rogram case. The main difference is that we must convince the linker to 
eink the segments in a particular order, with the data segment containing the 
uriver header block coming first in the file. 


35. 
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Communication from Assembly to C 


The assembly language header will contain a pointer to a small assembly 
language strategy routine, which will move the pointers to the reques\__ 
packet from ES and BX to the stack, and then call the C strategy routine 
The interrupt service routine should generally remain in assembly language 
so it can run as fast as possible and the only communication necessary is tha 
its address must be declared PUBLIC so it can be registered and deregis 


tered within the C part of the device driver. YU 
WY 
Communication from C to Assembly ‘e 


The main parts of the communication back to assembly language are the” 
calls to the DevHelp routine, which is called with all of the arguments in thy 
registers and all results returned in the registers. This is done by creating , 
structure containing the registers that is passed to the assembly language 
calling routine, which loads the registers with these values and calls the” 
DevHelp routines directly. This is entirely analogous to the method DOLY 
programmers use to call advanced DOS programs from C. & 
We will also simplify the error code return procedure by making ouz 
assembly language wrapper return the error (1 or 0) in the AX register. 
making the wrapper an integer function whose return code indicates whethe— 
an error occurred or not. oe, 
In addition, it is necessary to provide assembly routines to access the 1/€ 
ports directly. We are essentially replacing the inp and outp routines thar 
would normally be called as library routines, since these routines would be ed 


8060 


a different segment and won’t work from the device driver level. WY 
Ww 
POINTERS IN A C DEVICE DRIVER a 


YS 
Even though this is a small model C program, you must be careful to make 


all pointers you pass between the C code and the assembly header into FAR 


pointers. This is required because you can not in general be sure whether th 
variable will be located in stack space or pointed to by the data segment re® 
ister. This single point is the most troublesome: nearly every bug uncovere@ 


during development of this device driver sample turned out to be a near” | 


Seo¢ 
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pointer that should have been a far pointer. Again, if you declare that a vari- 
arable is a pointer, make sure you include the keyword far. 
a, 


a@THE ASSEMBLY LANGUAGE HEADER PROGRAM 


' The declarations in the assembly language program are critical and they 
Mmnust be exactly those shown below: 


fs -SEQ ;Use the segments in the order listed 
Mm .286p ;Use 286 instructions 


;group the segments into the correct order 
AM™GROUP group NULL, DATA, CONST, BSS, LAST D 
aus group _TEXT, END TEXT 


amthese segment names are not arbitrarily chosen, and are in fact those that 
the C compiler uses. By declaring them all here, we are saying that all of 
chem will be part of either the code (CGROUP) or the data segment 
XDGROUP). 


o™ 
The Device Driver Header 


All device drivers must start with a particular 22-byte header block and this 
dlock must be first in the NULL data segment. In this example, we will 
MNescribe a device called FRED$, which will be opened and used from a C 
emsrogram, and which has the same characteristics as the previously described 


gen ctrabyte ucDAS-8PGA Analog-to-Digital converter. 


NULL SEGMENT word public ‘BEGDATA' 
public dev header 
(‘y public devhelp 
eDevice driver header for the FREDS driver 
dev header equ $ 


pir to next dd OFffTTfftth ;means loadable 

evice_ attr dw 8880h ;option bits 
ffst dw _text:strategy j;assembly strategy routine 
-eserved dw -1 

yev_name db ‘FREDS  ' sdevice name 

aes2 dw 4 dup (0) 

o 

om 


om 
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data needed for device follows 


_devhelp dd ? ;This is the entry pt to 
; the device help routine 

_mbuf selector dw ? ;gdt selector goes here 

_int_ievel dw 3 ;interrupt level- could 


;be changed by POS 


SOOO OOOOCOCE 


NULL ENDS 


Then the following segments must be listed, empty, in this order to tell thuy 


linker they should be linked in this order &) 
WY 
_DATA = segment word public ‘DATA’ ‘> 
_DATA ends pod 
VU 
CONST segment word public ‘CONST! & 
CONST ends 
VY 
_BS5 segment word public ‘BSS! ‘oe 
BSS ends 
~ OU 
;Dummy segment symbol so we can tell OS/2 the end of our da\_) 
LAST D segment word public ‘LAST DATA’ 
_last_d equ S ;address of last data Y 
LAST D ends WY 
public last d ;addr of end of data segment , 
~ ~ WY 
LY 


The LAST_D segment is used to generate a constant indicating where the 
last word in the data segment is located. 


THE STRATEGY ROUTINE 


000 <¢ 


The assembly language strategy routine is pointed to by the strategy offs\__ 
in the device driver header. It merely serves as a wrapper to call the /* 

strategy routine that does all the work. All it does is push the ES and B | 
registers onto the stack so that they can be retrieved by the C strategy | 


= 


THE C STRATEGY ROUTINE So7 


Ait. 


™)routine as arguments in the form of a long pointer to the request packet 
structure 
o 


om a a a aa 
4 Code segment starts below 
©. Entry point to Strategy routine 
o ; s=oSSPS PS ae EE ee ee ee ee ee ee ee Ee EE EE Se ES ee ee ee ee ee ee ee ee ee ee ee ee ee ee EE EE EE EE SE ES EES 
® text SEGMENT word public ‘code’ 
on assume cs: TEXT, ds:DGROUP, es:nothing 
> 
)STRATEGY PROC FAR 
a: INT 3 ;debugging 
push es ;On entry es:bx pnts to request packet 
i push bx ;put them on stack for C-call 
mm, call strategy c ;call € strategy routine 
pop bx ;restore registers 
om 
pop es 
ao ret 


STRATEGY ENDP 


J 


am The C strategy routine must, of course, be declared as EXTRN within the 
assembly language header so that it can be resolved by the linker: 


a extrn strategy c:near ;C-strategy routine 


@Note that the C routine is declared as NEAR so that a near call is made, 
since all of the code will be in the same segment. 


~~, 


ao THE C STRATEGY ROUTINE 


"The C strategy routine receives the long pointer to the request packet as an 

argument to the function and simply implements a switch statement to 
decide which command to act on. The Ipreq structure is simply the C defi- 
nition of the request packet 


0080090 
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typedef struct Request packet 


begin 
BYTE  reqlength, /*length of request packet af 
devunit, /*device unit code “7 
reqcommand; /*command passed to driver 7 
USHORT reqstatus; /*return status bits here ed 
ULONG regreserved, /*resrved or 4 
que link; /*queue linkage ay 
BYTE fcategory, /*\0 function category ay 
fcode; /*\0 function code mJ 
LONG far “GioParams, /*data passed to driver a 
“GioData: /*data returned from the driver*/ 


606860800008 OE 


end far *lpRequest; 


It is also convenient to define the structure of the packet used at initializaX/ 


tion time with its own structure Cy 

typedef struct Init packet /“bytes are aligned */ @ 

/*“differently in this packet a | 

begin posi 

BYTE  reqlength, /*“length of request packet */ @ 

devunit, /*device unit code ay & 
reqcommand; /*command passed to driver oy 

USHORT reqstatus; /*“return status bits here “| 

ULONG reqreserved, /*reserved */ @ 
que link; /*queue linkage set 

BYTE  fcategory; /*10 function category i O 

ULONG IpDevHIp, /*address of dev help routine */ (> 
InitArgs; /*“initialization arguments ei 

BYTE drivenum; /* drive number for Ist i? Piao 

/* block device unit */ @ 


end far “Iplnit Packet; i) 
— wy 
The actual routine simply calls other routines based on the reqcommanc__ 
value: 


phases s se device driver strategy foul ine=-- oss s-Soc==— * / 
void strategy c(Ipreq) 
IpRequest Ipreq; 


begin 
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/*interpret the command to the driver 
switch( lpreq->reqcommand ) 
\ 9 begin 
ma case INIT: 
initdevice(lpreq); /*initialize the device 
break; 
or 
case OPEN: 
devopen( Ipreq); /* open the device a 
©) break; 


case CLOSE: 
) devclose(Ipregq); /*close the device 
a) break; 


‘. case GENIO: /*generic |/0 Control cmnds */ 
M  Genl0Ctri1(Ipreq); 


om break; 


MO) default: /*“otherwise set error bits 
a> Ipreq->reqstatus = GEN ERR + 

ERR UNKNOWNCOMMAND + DONE BIT; 
o break; 


My end /*switch®/ 
end 


slp 
“Ns f 


rr 
THE INITIALIZATION ROUTINE 


Yhe device initialization is now done at the C level and amounts to saving 
emhe pointer to the DeviceHelp routine and requesting a slot in the global 
descriptor table. Both of these values are stored in the data segment list just 
after the device driver header, and the locations are thus declared extern in 
he C program and PUBLIC in the assembly language program. 


oy ee odes es oe device initialization routine------------------ x | 
— @Mpxtern ULONG devhelp; /*“address of device help ar 
/*routine set at init a 


OYoid initdevice(lpreq) 


»o@@ 
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IpRequest Ipreq; 


begin 
IpInit Packet Ipi; 
union REGS reg; /“used to load registers */ 
union REGS far “preg; /* for devhelp calls - 


int errnum, far “mbuf, Ic, 1d; 


preg = &reg; /*to pass args to Dev Help*/ 
Ipi = (IpInit Packet) Ipreq; /*cast ptr to structure */ 
devhelp = Ipi->IpDevHIp; /*save device help address*/ 


PETE EET TTT 


Returning the End Addresses 


It is critical that you return the end addresses of the data and code segments 

as part of the exit from the initialization routine. These are actuallyw’ 
compile-time constants, but you must return them as addresses. In the 
assembly language header, they are declared as PUBLIC: 


( 


w/ 
public _last d ;o0ffset to end of data segment LY 
public last _c ;o0ffset to end of code segment 

In order that they be treated as addresses by C, we declare them as if eae 
were functions. ” 
/* dummy routines -actually pointers “/ 

extern void near last _c(); /* to code ot ied 
extern void near last _d(); /* and data “1 © 


Then, to pass these addresses back at exit time, we simply put them in the 
upper and lower parts of the pointer to the DeviceHelp function. Recall that) 
the second pointer must be returned as zero for all character drivers: 


oe 
le = (int)last_c; /*offset to end of code segment */ | 
Id = (int) last_d; /*“offset to end of data segment*/ 
Ipi->IpDevHIp = , 
MAKEULONG(Ic, 1d);  /*return these in parms in pkt ‘/@ 
Ipi=*lnitArgs = OL; /"must be zero for char driver */ 


To reserve a GDT selector, we must see how to make calls to the devhelp 


routine from C. 
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CALL DEVHELP FROM C 


Since all calls to the DeviceHelp routine are made with all the arguments in 
the registers, we must create a structure into which we can place the argu- 
ments and from which we can retrieve results. This is much like the register 
qmstructure used in DOS programming, except that we have included the ES 

register for simplicity. Note that in protected mode you must put either a 

valid value or NULL in ES at all times. 


> 


struct WORDREGS { 


Oo unsigned int ax; 
aM unsigned int bx; 
unsigned int cx; 
‘al unsigned int dx; 
O™ unsigned int si; 
a unsigned int di; 
unsigned int cflag; 
) unsigned int es; /* note ADDITION of ES to this */ 
m™) B; 


W/* byte registers */ 


struct BYTEREGS { 


om unsigned char al, ah; 
unsigned char bl, bh; 

fy unsigned char cl, ch; 

™, unsigned char dl, dh; 
om ? 

Minion REGS ¢ /* overlays two structures os 
struct WORDREGS x; 
struct BYTEREGS h; 

A> }; 

a 

‘ Allocating a GDT Selector 

g 

Pale’ 


_~lhe procedure for allocating a GDT selector amounts to passing the far 
address of the location where the selector is to be returned to the DeviceHelp 
Youtine. This is done by breaking the 32-bit address into two parts and 


qmputting them in the ES and DI registers: 


IDROI 
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[Roneaneneminse Allocate a GDT selector--=------==+-=-—---]- * / 
mbuf = &mbuf selector; /*“address where selector “/ 
/*will be returned i 
reg.x.di = (int)&mbuf selector; /“offset part of address “/ 
reg.x.es = 
(int)((long)mbuf >> 16);  /*segment part of address*/ 
reg.x.cx = 1; /* get only 1 GOT seletr */ 
reg.h.dl = 
DevHIp_AllocGDTSel; /*number of DevHIlp func “*/ 
errnum = CDevHelp( preg); /*call C dev helper routn*/ 


6060000008008 OC 


CALLING IN AND OUT ROUTINES 


In order for your initialization routine or any other part of your driver to b6w 
able to access the I/O ports of your device from C, you must write your own) 
inp and outp routines in the assembly header. Fortunately these are 
extremely simple to write: 


public _inp ‘C-call £o in=port routine 7 
public outp ;C-call to out-port routine 
WY 
: INP routine to be called from C Y 
; oS EE Ee EE EE EE EE EE ES EE EE EE EE EE EE EE EE EE EE EE EE EE SE EE Ee ee ee Se ee ee ee ee ee ee ee ee ee ee ee ee ee ee eS ww 
; int inp(int port); ‘. 
_ INP PROC NEAR WY 
push bp oe 
mov bp, sp ;set frame 
mov dx, [bp + 4] ;get port address ~ 
xor ax, ax ;set ax = 0 a, 
in al, dx ;return argument in ax 
pop bp sand base pointer Y 
ret YJ 
INP ENDP Y 
> ooo-"'_c:.clccclccl::aoen ec SCS SCS SCoSooSSSoccoQJoQoSoScSo00000oooooqQocoocCoocooooQocoJoOJSoQQoSoSlS lS SSS ay 
WL 
wo 


we 


we 
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void outp(int port, int value) 


_OUTP PROC NEAR 
om push bp ;save base pointer 
mov bp, sp ;set frame 
a) mov dx, [bp + 4] ;get port address 
oo, mov ax, [bpt6] sand value to send out 
- out dx, al ;send value out 
pop bp sand base pointer 
eo rec 
am_OUTP ENDP 


emThey must be declared as extern in C and PUBLIC in the assembly module. 
anln addition, you must specify that the default libraries are not to be linked, 
so that the C-library versions of these routines are not linked instead. 


> 


extern int 


2 


»9 


I 


near inp(); 
extern void near outp(); 


de DEVICE OPEN ROUTINE 


cow henever we open our device, we will register its interrupt. This means that 
we need to tell OS/2 the interrupt level, whether the interrupt is shared, and 
the address of the interrupt service routine. The service routine itself will be 
written in assembly language and declared PUBLIC, and declared extern in 


> We also obtain the device’s current handle from the OPEN call, and only 
open the device if the handle value is currently zero: 


™ 


Droid devopen( Ipreq) 


al. 
wn 


~e 


) I\IpRequest Ipreq; 


oegin 
O) union REGS reg; 
am, union REGS far “preg; 
int err; 


apreg = éreg; 
if (handle == 0 ) then 
om 


399 


aslenistetatetaeteseteatatan device open fOut i Nne=-H- sas --=4-=4--4454=="/ 


/“used to load registers “/ 
/*for devhelp calls ss 
/*to pass args to Dev Helper “*/ 


/*“open only if not already open*/ 
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begin 

handle = Ipreq->devunit; /* copy handle number “*/ 
Ipreq->reqstatus = DONE BIT; /* set done bit a 
pRarosee set up request to use interrupt -------------- KY 
reg.x.ax = (int)inthandler; /“addr of interrupt handler*/ 
reg.x.bx = int level; /*set interrupt level 7 
reg.h.dh = 0; /*no interrupt sharing oy 
reg.h.dl = DevHIp SetIRQ; /*set interrupt request ss 
reg.x.es = NULL; /*es not used, set to NULL */ 
err = CDevHelp(preg) ; 


if (err) then 
Ipreq->reqstatus 


GEN ERR+ 
ERR GENERALFAILURE + DONE BIT: 
end 

else 


Ipreq->reqstatus GEN ERR+ 


ERR GENERALFAILURE + DONE BIT; 
end 


GENERIC !/O CONTROL CALLS 


SOOO OHOOOOHOOOOCOOOEO 


The generic I/O control calls are handled with a second switch statement, 
In our routine we first check to see that it is category 11 (general device 
I/O) and second that it is one of the expected user-defined function codes. 


C 


[Ceres arses sea Generic 170 Contre | Sse ss=SSseseSess—— “i 
void Genl0Ctr1(Ipreq) 
IpRequest Ipreq; 


begin 


if (lpreq->fcategory == GENDEV) then 
begin 
switch( lpreq->fcode) 
begin | 
case SETGAIN: /*set the gain for the ADC*/ 
SetGain(lpreq); 
break; 


SOOO SOOOOOROOOOE 
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case SETMUX: /*set the number of mf 
SetMux(Ipreq); /*multiplexer channels of 
break; 

default: 


Ipreq->reqstatus = GEN ERR+ 
ERR UNKNOWNCOMMAND + DONE BIT; 
end /* switch*/ 
end be ae 


3e9860099999 


Melse 
yon Ipreq->reqstatus = GEN ERRt+ 
| ERR UNKNOWNCOMMAND + DONE BIT; 
ai 
amend 
a 


DEVICE ACCESS FROM GENIOCTRL COMMANDS 


Ortnere are two ways to command the actual device: either store the parame- 

ters and load them all when data acquisition 1s initiated, or have them take 

omeffect immediately. The SetMux routine simply stores the multiplexer value 
in a global static variable adcmux and the SetGain routine actually changes 
the hardware setting using calls to the outp routine. 


Presses Set Multiplexer-------------------------- ad 
om ; 
void SetMux(1lpreq) 


O) \1pRequest Ipreq; 


begin 
on, long far “muxadd; /*address of mux value =i 
-. int muxval; 


Onuxadd = Ipreq->GioParams; /*get address of mux value */ 


e@ynuxval = (int )*muxadd; /*get actual value = 
if ((0 <= muxval) AND (muxval <= 7)) then 
adcmux = muxval; /* copy into global parm */ 
Mp|preq->reqstatus = DONE BIT; /* set done bit oF 
end 
nner Sét Gai fase see Saar ac aremeee tose se kee 7 


Owoid SetGain(lpreq) 
| a IpRequest Ipreq; 
ra 

oo 
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begin 
int gainval=0; 
long far “gainadd; 


gainadd =Ipreq->GioParams; /“address of gain value 
gainval = (int)*gainadd; /*actual gain value 


/* set the gain value now */ 
outp(PORT BASE + ADC GAIN, gainval); /*send the value out*/ 
Ipreq->reqstatus = DONE BIT; /*set done flag a 
end 


CLOSING THE DEVICE 


SOOOSHOOOOOCOOSCE 


When the user is finished accessing your device, he should issue a CLOSE__ 
command, which your driver should interpret by just de-registering the 


Ww 
interrupt. 
| @ 
pO enoreesssssee= Pevice- Close Rout | peters nsesoseeeeeHs */ 
VY 
void devclose( Ipreq) 
IpRequest Ipreq; ww 
\ 
begin — 
union REGS reg; /“used to load registers oa 
union REGS far “preg; /*for devhelp calls “7 Ly 
int err; 
WY 
pPeg = &reg; 7, 
handle = 0; /* release handle */ 
req.x.bx = int_ level; Y 


reg.h.d]l = DevHIlp UnSet!IRQ; /* release interrupt request */@ 

err = CDevHelp(preg); 

if (err) then 
Ipreq->reqstatus 


GEN ERR+ ERR _GENERALFAILURE; 


else 
lpreq->reqstatus = DONE BIT; /*set done bit*/ 


end 
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AA 


COMPILING AND LINKING YOUR DRIVER 


The C part of your driver must be compiled using the Small memory model 


cl /c /Gs /Asnw /Zpe /Fc driver.c 


an 
where 
m/c means compile and do not link. 
OY/Gs means remove stack checking. 
O/Asnw is the memory model specification: 
rN 
As Small model C. 
Oo n Use near pointers. This is overridden for each one. 
oO Ww Don’t load DS on entry to routines. 
©)/Zpe packs structures and enables language extensions. 
OYFe generates a .COD file with assembly language listing to assist 
ro, in debugging. 
om, 


Assembling the Header File 


o 
The MASM call is 


masm -Mx drivhead,,drivhead. Ist; 


»®@ 


~mWhere -Mx indicates that all public variables are to be case sensitive to be 
consistent with C conventions. 


99 


>> 


- 
Linking the Resulting File 


(The statement in the driver MAKE file is just 


OMriver.sys: driver.obj drivhead.obj driver.def 
@ link @driver.1 


(where the response file contains 


Ait i. 
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drivhead.obj + driver.obj /A:16 /NOD /MAP 
driver.sys 

driver.map 

slibce. |i bt 

os2.1ib 

driver .def 


and the DEF file contains 


LIBRARY DRIVER ;Specifies DRIVER as a dynamic link module 
PROTMODE ;Runs only in protect mode 

CODE PRELOAD ;Device driver - preload 

DATA PRELOAD ;Device driver - preload 


as before. 


CALLING THE DRIVER FROM C 


©8600 000000000O OE 


C 


The following simple program opens the driver, sets a couple of parameters, 
and closes it. 


/*“driver calling test program */ 
#include <cdefs.h> 

#define INCL BASE 

#include <os2.h> 

#include <stdio.h> 


#define SETCLOCK 0x40 
#define SETGAIN Ox41 
#define ADCGO Ox42 
#define SETMUX 0x43 
#def ine GETCOUNT 0x44 
#define Devicel0 11 


void main(); 


Leben enn wb bbb wb wb wb wb bb ow wb eb te be ee i ee i I I I I I I 
ER me TE ane POE Sr oe SE een ee CUT Lt an SOE OEP Re nin OEE) oN Seren ntwe va Mme er Cw ec Mose aN aR EOS Porn 


void main() 

begin 
int clockword, i, count; 
-HF ILE handle; 
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USHORT result, attr, oflag, omode,action; 
ULONG fsize, reserved, muxword, gainword; 
unsigned long far “SemHandle; 

long dataword; 

int ™ps 


90000009 


(\fsize = OL; 
attr = 0; 
oflag = 1; 
Myomode = 0x0012; 
dataword = Q; 
muxword = 0; 


an/* open the ''FREDS'' device a 
result =DosOpen(''fred$'', &handle, Saction, fsize, 
| attr, oflag, omode, reserved); 
“ ' 1 
oy set the Be il / 
muxword = Q; 
Mresult = DosDevl0Ct1((PVOID)(long far *“)&dataword, 
o (long far “)&muxword, 
SETMUX, Devicel0, handle); 
~» 
ol set the gain to +/- 5v oF i 
gainword = 0x0; 
Mresult = DosDevlOCt1((PVOID)&dataword, (PVOID)&gainword, 
~ SETGAIN, Devicel0, handle); 
@: close the device 
MosClose(handle); 
nd 


a 


ol HE DRIVER ASSEMBLY LANGUAGE HEADER 
PROGRAM 


(The amount of assembly language is now minimal and amounts to wrappers 


| efor the strategy routine, device helper routine, and in and out routines. 


92000 
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;***** Assembly language minimum module for device drivers* 
. SEQ ;Use the segments in the order listed 
.286p 

page , 132 
extrn strategy c:near ;C-strategy routine 
public inp ;C-call to ftn=port routine 
public outp ;C-call to out-port routine 
public CDevHelp ;C-call to device helper 


public mbuf selector 
public _inthandler 
public int level ; level of interrupt 


;group the segments into the correct order 
DGROUP group NULL, DATA, CONST, BSS, LAST D 
CGROUP group  _ TEXT, END TEXT 


SOOOOSCCOCOOCCC SE 


; Start of the Data Segment pa 
: Must start with the device header information ww 
pe es OST oS eee en a ee ee 
NULL SEGMENT word public 'BEGDATA' Y 
public dev header | ws 
public devhelp 

-Device driver header for the PGA8S driver Y 
dev_ header equ $ WwW 
ptr to next dw OTT Tth ;-means loadable ) 

= "= Ww 

dw =] 

device attr dw 8880h ; — 
of fst dw _textistrategy ;strategqy routine VW 
reserved dw =| | 
dev_ name db ‘FREDS >device name Y 
res2 dw 4 dup (0) CJ 
aie eee ae ae end of actual device neager““-<<9==—-<9<5=<— Y 
; data needed for device follows Wy 
_devhelp dd ? sentry pt to the device help routine 
_mbuf selector dw ? ;gdt selector goes here 7 
_int_level dw 3 ;could be changed by POS routine 
NULL ENDS 
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_DATA = segment word public ‘DATA’ 
“DATA ends 

CONST segment word public ‘CONST 
CONST ends 

_BSS segment word public ‘BSS! 
“BSS ends 


>900000080890009 


| 
| 
| 
| 
| 
rr 
o) 
cn) 
—N 
™~S 
ip) 
ct 
= 
49) 
@ 
=) 
Oo. 
O 
—h 
O 
= 
“% 
. 
ab) 
ct 
mw 


LAST D segment word public ‘LAST DATA’ 


-, public last d 

o _last_d equ S ;address of last data 
LAST_D ends 

om 


? 
@e Structure of a request packet 


O>KTMAX equ 18 ;Maximum size of packet 
m 
Packet struc 
PktLen db ? ; Length in bytes of packet 
OrktUnit db ? ; Subunit number of block device 
ktCmd db ? ; Command code 
PktStatus dw ? ; Status word 
OyktDOSLink dd ? ; Reserved 
ktDevLink dd ? ; Device multiple-request link 


PktData db PKTMAX dup (7?) ;specific packet data 
-acket ends 


Code segment starts below 
Entry point to Strategy routine 


TEXT SEGMENT word public ‘code’ 
assume cs: TEXT, ds:DGROUP, es:nothing 
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eee 


STRATEGY PROC FAR 


C 


INT 3 ;debugging 
push es ;on entry es:bx pnt to request packet\y 
push bx ;put them on stack for C-cal] LY 
call strategy c j;call C strategy routine 
pop bx ;festore registers Y 
pop es J 
ret 
STRATEGY ENDP Y 
a a a aR, 
: INP routine to be called from C fn 
, see ease esas seese se esaseasesssssessesesssssasssssssssssas=S 
int inp(int port); LY 
_ INP PROC NEAR Y 
push bp Ww 
mov bp, Sp ;set frame ey 
mov dx, [bp + 4] ;get port address 
xor ax, ax YY 
in aly. ax ;return argument in ax WV 
pop bp sand base pointer | 
ret Y 
YO 
OUTP routine to be called from C Ww 
: void outp(int port, int value) md 
Ww 
_OUTP PROC NEAR y 
push bp ;save base pointer 
mov bp, sp ;set frame VY 
mov dx, [bp + 4] ;get port address WY 
mov ax, [bpt+6] sand value to send out 
out dx, al ;send value out Y 
pop bp sand base pointer WV 
ret 
_OUTP ENDP ” 
Ww 
a ge ee NTE a oii ene es 


sDevice Helper interface routine to C 


o 
o 
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o 

a This wrapper copies the values into the registers from the 
;Registers structure, calls the DevHelp system routine 
,and puts the results back into the structure on exit. 

Ms Note that the CX register is not used on exit, and that 
;the error indicator returned in the C-flag is returned as 
,;a result of the function in the actual AX register 

M) (not in the structure's AX register) 


oN 
; #include <dos.h> 
“yy BOOL devhelper(struct WORDREGS “w); 
a eG ee ee rr eer a eens 
; structure of registers passed to devhelper cal] 
a g 
@egisters struc 
axo d ? -a ist 
> x W x Eeats er 
bxo dw ? ;bx register 
‘a CxO dw ? ;cx register 
a Exo dw ? sl Pog Sree 
SiO dw ? $Si reqister 
“fy dio dw ? ;di register 
rN cflag dw ? ;flags register 
eso dw ? ;eS register-must be NULL 
o ;Or real value 
@egisters ends 
Ocdeviieip PROC NEAR 
W\- crc crc rc rr rr rrr 
gpevhe Ipstack struc 
oldbp dw ? ;saved bp 
M) retadr dw ? ;short return address 
regadd dd ? ;long pointer to seg structure 
devhelpstack ENDS 
a ee eee eee 
am INT 3 ;debugging 
push bp 
oy 
mov bp, sp ;set frame 
™) push di ;Save index regs 
om push Si 


©) get values from addresses 
les di, [bp + regadd] ;get address of start 


Fa’ 
o~ 
~ 
~~ 
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mov 
push 
mov 
push 
mov 
mov 
mov 
mov 
mov 
Pop 
Pop 
cal] 


sof structure 
ax, 865 (01].S10 


ax ;Save es and si for last 
aX, €5:| di |.es0 

ax ;Save es and si for last 
ax, es: [di |.axeo ;ax-value 

cx, es:[di].cxo scopy all values from struct 
dx, esi[di].dxo ;to the actual registers 
bx, es:[di].bxo sbefore making the call 

di, es:[di|.dio 

es 

Si ;restore registers for call 
[ devhelp] ;call the dev-helper routn 


;return the values to the calling program 


push 
lahf 
mov 
xor 
Pop 
push 
push 
les 


mov 
mov 
mov 
mov 
pop 
mov 
pop 
mov 
mov 


and 


Pop 
pop 
Pop 
rer 


_CDevHelp 


ax ;save ax 
;copy flags into ah register 

cl, ah ;copy to cl 

chs ch ;zero upper byte 

ax ;resStore ax 

es *Save these 

di ;for last loading 


di, [bp + 4] sget address of 
;start of structure 


es:[di].cflag, cx j5return carryflag value 
es:[di].axo, ax j;return value of ax 
es:[di].bxo, bx jreturn bx-value 
es:[di].dxo, dx jreturn dx-value 
ax 
esi[di|.dio, ax freturn di 
ax sand es 
e5:[di].<eso, ax 
ax, CX ;get carry flag into 
sAX for return 

ax, | ;only carry bit is returned 
Si ;restore real si and di 
di | 
bp sand base pointer 

ENDP 


SSHOSSSHSHHSHSHSHHOHOHSHOSOOOOOOOSOOOOCSCCSE 
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'»9e00000 


; Interrupt Handler 
gg, SORES SSS Se Sn SS SSS Se SSS 
_INTHANDLER PROC FAR 
erc ;interrupt was ours 
oo ret sand exit 


©) INTHANDLER ENDP 


a 

TEXT ENDS 
Oe 
o Dummy routine to generate symbol marking end of C-Code 

y g ¥ g 
cND TEXT Segment word public ‘CODE 
public last c ; last word of c-code 

am last _c equ S 


END TEXT ENDS 
~ - 


End of CODE segment 


THE DRIVER C PROGRAM 
om, 


ill of the actual functions are interpreted and carried out in the C part of 
%e program: 
m* KAKAKKKKKKAKKKRKKERKE 
@Ainclude <cdefs.h> 
#define INCL BASE 
\ Jinclude <os2.h> 
o 
define INIT O 
_define READ 4 
Mefine OPEN Oxd 


* re ale JL we te I I LL 
C- device driver CORE a Cnn een ee ene OMe ge 


2600 
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CLOSE Oxe 
GENIO 0x10 


#def ine 
#define 


#define 
#define 


PORT BASE 0x300 
ADC GAIN 3 


#define 
#define 
#define 
#define 


DONE BIT 0x100 
GEN ERR 0x8000 

ERR UNKNOWNCOMMAND 3 
ERR GENERALFAILURE Oxc 


#define 
#define 
#define 


DevHIp AllocGDTSelector Ox2d 
DevHIp SetIRQ Ox1b 
DevHIp UnSet IRQ Oxic 


ov 


/*address of device help 
/*“routine set at init 


extern ULONG devhelp; 


extern void near inthandler(); /*entry to intrpt handler 

extern int near CDevHelp(void far *); /*wrapper to call 
/*“device help routine 

extern int mbuf selector; /*gdt allocated goes here 

extern int near inp(); 

extern void near outp(); 


1. 
e e xe 
extern int int level; /“interrupt level used 
ab JE ow wb ob ob Lo al ob wb A a wl J J I 
GN IN IN AN EN AN EIN IN IN IN IN IN EN EN EN IN AN AN EIN AN EN EN EN EIN IN AN AN IN EN EN 


[BRKRKRERRKK MIRAE Re RARE RES 


/* pointers to tne end of the code and data segments 
dummy routines 
Rane pointers to code 


sc sc wl wb ob ob Le I I I 
WNIN OREN IN INARI IN INI INNIS 


void near last c(); 
extern void near last d(); 


wb wb wb I Le 
Fe ener omen epey te Hn ey eee seen 


extern 


ln at. 
Ven 


/* global variables used within the C program 
/*device handle returned on open 
“multiplexer value saved here 


wh Jb wb 
WN IN AN ANON IN IN INN IN IN EN IRIN IN INNIS x WINN IN AN INN IN 


unsigned handle; 
int adcmux; 


b] 
wh wb oe Ab Lb ob I oe 
ia IN AN AN IN IN IN ANON AS 


nA 


ray 


a 


cA’ 


These structures are used to pass information to the 
Device Helper routine. Note they are like the DOS 
definitions except that ES is added. You must ALWAYS 


i a a 


oF 


SOOO OOOOOCCCO- 


* j a, 
* / | 
* / WY 
“yO 
* / 
* / 


* WW 


we ob Le 


* 7 
* Pond 
al. he 


cas 


AS 


eeeedéce 
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yruct WORDREGS { 
unsigned int ax; 
unsigned int bx; 
unsigned int cx; 
unsigned int dx; 
unsigned int Si; 
unsigned int di; 
unsigned int cflag; 
unsigned int es; /* note the ADDITION of ES to this */ 
}; 
O* byte registers a I 
amruct BYTEREGS i 
unsigned char al, ah; 
ey unsigned char bl, bh; 


Titi ft. 


a unsigned char cl, ch; 
unsigned char dl, dh; 
co 7 
= | 
* general purpose registers union - *Y 
overlays the corresponding word and byte registers. a 


aagion REGS { 

Struct WORDREGS x; 
o struct BYTEREGS h; 
o 


whe J ob ob oe I 
IN ANON IN IN IN ON IN IN IN IN EN IN IN IN IN IN IN IN IN IN IN OIN IN IN IN OIN IN IN INI IN INN BIN ININBIN INRIA / 
poke 
. 
- 
wn 


3; 
Definition of the Request Packet structure a | 
a ee Sci et Red cia Ra a ae creme anette a ota * / 
jpedef struct Request packet 
begin 
a BYTE reqlength, /*length of request packet ae 
7 devunit, /*“device unit code af 
o reqcommand; /*command passed to driver or 
USHORT reqstatus; /*“return status bits here as 
ULONG reqreserved, /*reserved mf 
quelink; /*queue linkage i 
aBYTE  fcategory, /*\10 function category 7 
fcode; /*|10 function code of | 


Tit. 


Yy 
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Ww 
LONG far *“GioParams, /*data passed to driver aed 
*GioData; /*data returned from the driver*)/ 
end far “IpRequest; 
Fi KEKE KKKKKRKKKKEKRKRKKRKRKEKEKKKRKREREKKKKKRREKKKKKKKKKERE Y 
/* Definition of the request packet structure used at *k 
/* initialization time ‘@ 
/* cyan an Sl ns Nic As cin a Acca ha fetta laa le cel asta uate: sec tae cb es tga le as lb da cn Seah ete ea aa * f 
typedef struct Init packet /*bytes are aligned aed 
/“differently in this packet ‘@ 
begin 
BYTE  reqlength, /*length of request packet *S 
devunit, /*device unit code “9 
reqcommand; /*command passed to driver ‘= 
USHORT reqstatus; /*return status bits here Dad 
ULONG reqreserved, /*resrved 7 
que link; /*queue linkage ‘a 
BYTE  fcategory; /*“|0 function category "a 
ULONG IpDevHIp, /*address of device a ed 
/*helper routine ‘oO 
InitArgs; /*“initialization arguments * 
BYTE drivenum; /*drive number for Ist : 


4, 


eo€ 


/*block device unit 
end far “IplInit Packet; 


bebe bene bow bw wb wb wb wb bb wb wb we I I I I 
ZN GN AN AN ON AN AN ON AN AN AN ON AN AN AN IN IN AN ONIN AN IN DN BN BRAN NBN ONIN EN ON BN IN INN IN IN ONIN IN IN IN IN IN IN IN IN IN IN IN IN IN IN INN EN 


L 


é 


/ 

/* Strategy routine called by device driver 
/* assembly header 
j 

; 

/ 


+ 


‘6 


«J 
aN 


“to interpret commands to the driver and execute them 
“ After command execution is complete the reqstatus bits’ 


wl 


* are set in the request packet VY 
/ A AE et RN Se ee AT RD DT NE AER ACES AY rc SRT TE ERR TON STII yee Virsa RES TET * / 
void strategy c(Ipreq) Y 

IpRequest Ipreq; Ty 
begin bad 
/*jinterpret the command to the driver Ww 

1 -> 
switch(Ipreq reqcommand) &) 
begin 
case INIT: YY 
initdevice(Ipreq); /*initialize the device 
break; 
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oo 
m case OPEN: 
devopen( Ipreq); /* open the device a | 
Oo break; 
m 
case CLOSE: 

2 devclose(Ipreq); /*close the device “jf 
> break; 
nm case GENIO: /*generic 1/0 Control commands*/ 
an Genl0Ctr1(lpreq); 
ma break; 
©) default: /*“otherwise set error bits a 
my Ipreq--reqstatus = GEN ERR + 

| ERR UNKNOWNCOMMAND+ DONE BIT; 
= break; 
Mend /*switch*/ 

end 
O. KKKKKKKKKKKKKRKKRKKKERREKERRKRKRRRKKKKKKKKKAKEREERKKRKKKKEE / 
a Device Driver Initialization Routine 9 
x Firsts cis ake Mkt at al 9 ae a ie eal a Se al nae ec gah igh te gee Oe * / 

‘oid initdevice(lpreq) 
o IpRequest Ipregq; 
megin 

IpInit Packet Ipi; 

©) union REGS reg; /*“used to load registers ai 
™) union REGS far “preg; /*for devhelp calls ay 


int errnum, far “mbuf, Ic, ld; 


Greg = &reg; 


api = (IpInit Packet) Ipreq; 
-evhelp = Ipi->IpDevHIp; 
o 


_*allocate a GDT selector 


(uf = é&mbuf selector; 


o 


1eg.x.di 
2g-X.€S 


meg.x.cx = 1; 
meshed 
on 
on 
on 


= (int)&mbuf selector; 
(int)((long)mbuf >> 16); 


DevHIp AllocGDTSel; 


/*to pass args to Dev Helper*/ 
/*cast pointer to structure “*/ 
/*get device help address “*/ 


/* and save it “ 
a 
/*address where selector ee 


/*will be returned 
/* pass in es:di */ 


/*get only 1 */ 
/*“number of DevHIp functn*/ 
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errnum = CDevHe Ip( preg); /*call system device * / 
/*“helper routine a 

lc = (int) last _c; /*“offset to end of code segment*/ 

Id = (int)last_d; /*offset to end of data segment */\ 
Ipi->IpDevHIp = | 

MAKEULONG(Ic, Id); /*return these in parms in pkt J ipo 

Ipi->InitArgs = OL; /* must be zero for char driver*/W 

if (errnum) then /*set if error “1@ 
Ipreq->reqstatus = DONE BIT + | 

GEN ERR+ ERR GENERALFAILURE; YY 

else Ky 
Ipreq->reqstatus = DONE BIT; /*set done bit if no err™/ 

handle = 0; /*device handle initialized: “AY 
/*net in use * 

end WY 

[RRR RIKI KIRKE KK EKER ERE KER ERE KEKE RE RE RE KER ERE RE RE RE K | 

ha Open the Device ‘@ 


LEE ww ww wb wb ob wb wb ob ob ob ob be ee ee ee I i i I I I I 
Dl ail J 


void devopen( Ipreq) WY 
IpRequest Ipreq; Fy, 
begin Y 
union REGS reg; /*used to load registers ‘ke 
union REGS far “preg; /*for devhelp calls ef 
int err; WY 
WY 
preg = &reg; /*used to pass args to Dev Helper® 
if (handle == 0 ) then /*only open if not already open va 
begin L) 
handle = lIpreq->devunit; /* copy handle number ev 
Ipreq->reqstatus = DONE BIT; /* set done bit ee 
- WY 
/* set up request to use interrupt */ i) 
reg.x.ax = (int)inthandler; /*addr of intrpt handler */ 
réeq.x.bx = int_level; /*set interrupt level . 
reg.h.dh = 0; /*not allow interrupt sharing*h J 
reg.h.d] = DevHIp SetIRQ; /*set interrupt request wf 
reg.x.es = NULL; /*es not used, set to NULL & 


Oeoe¢ 
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err = CDevHelp(preg); 
if (err) then 
Ipreq->reqstatus = GEN ERR+ 
ERR GENERALFAILURE + DONE BIT: 


}6000090 


end 
Ose 
my Ipréeq->reqstatus = GEN ERR+ 
ERR GENERALFAILURE + DONE BIT; 
Ou - - 
on KAKKKKKRKRKKRAKAKRKKKRRRRRRRRRRRKRKRKRKKKRRKRRRRKRKRR KKK KRKKKRE 7 
* Generic 10 Control Handler -- sa 
Interprets Device Specific Commands a 
\ This routine interprets specific functions in specific*/ 
“ categories In this case, only the category GENDEV-11 “*/ 
, General Device Control is interpreted. All others are */ 
OS treated as errors a 
| a RKAKKARARARAKAE RAAB AKARKAR AREA RRREAKRRRERKKR RRA KKAERK j 
, Device specific commands -all must have bit 6 set 
) to be passed to handler a 
@refine SETCLOCK 0x40 
#define SETGAIN Ox41 
_Jefine ADCGO 0x42 
O%ef ine SETMUX 0x43 
metine GETCOUNT 0x44 
OY Only category to be checked for legal commands “ 
#def ine GENDEV 11 
/ SS SSS SSS SS SSS SSS SSS SSS SSS SSS SSS SSS SSS SSSSsSsssssssSs5=5% / 
id Gen|0Ctr1(lpreq) 
| IpRequest Ipreq; 
@yin 
o 
if (Ipreq->fcategory == GENDEV) then 
begin 
©) switch(lpreq->fcode) 
begin 
case SETGAIN: /*set the gain for the ADC*/ 
SetGain(Ipreq); 
break; 


Titi tg 7. 
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case SETMUX: /*set the number of 
SetMux(Ipreq) ; /*multiplexer channels ? 
break; 

default: 


Ipreq->reqstatus = GEN ERR+ 
ERR UNKNOWNCOMMAND + DONE BIT; 
end /* switch*/ 
end = /* if */ 
else 
Ipreq->reqstatus 


GEN ERR+ 
ERR UNKNOWNCOMMAND + DONE BIT; 


void SetMux(lpreq) 
IpRequest Ipreq; 


begin 
long far “muxadd; /*“address of mux value 
int muxval; 
muxadd = Ipreq->GioParams; /*get address of mux value ’ 
muxval = (int)*muxadd; /*get actual value : 
if ((0 <= muxval) AND (muxval <= 7)) then 
adcmux = muxval; /*copy into global parm 
Ipreq->reqstatus = DONE BIT; /* set done bit 2 
end 
/*ssssssssssssssssssssssssssssssssssssssssssssssssssssssa 
void SetGain(lpreq) | 
IpRequest Ipreq; Y 
WY 
begin | . & 
int gainval=0; 
long far “gainadd; WY 
gainadd =lpreq->GioParams; /*“address of gain value ‘& 
gainval = (int)*gainadd; /*actual gain value * 
‘oS 
/* set the gain value now */ , 


~ 


wl 
PAS 
{ 


outp(PORT BASE + ADC GAIN, gainval); /*send the value out 
Ipreq->reqstatus = DONE BIT; /*set done flag 


eeeo 
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‘oid devclose( lpreq) 
a IpRequest Ipreq; 
@ecin 
OY union REGS reg; /*used to load registers 
om union REGS far “preg; /*for devhelp calls 

int err; 


on 

amreg = &reg; | | 
nandle = 0; /* release handle oF 

Wpeg.x.bx = int level; 

mpeg.h.d] = DevHIp_UnSet IRQ; /*release interrupt req 
err = CDevHelp(preg); 
‘f (err) then 

O) l|preq->reqstatus 

Ise 
Ipreq->reqstatus = DONE BIT; /“set done bit 


GEN ERR+ ERR GENERALFAILURE; 


and 


= 
COMMUNICATING WITH DMA CHANNELS 
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\ Many data acquisition boards allow data to be transferred to memory 
\irectly without intervention of the processor. Such boards are called 
o@SDMA boards” and utilize the Direct Memory Access channel of the PC or 
S/2 to transfer data. This DMA approach is also commonly used by disk 
“arive interfaces as well as a number of LAN communication cards, so the 
©)MA controller is not totally free for your exclusive use. 
o) From the point of view of data acquisition, however, a DMA card is an 
adeal choice for high data rates in a multitasking system such as OS/2, since 
snere is no point-by-point overhead in acquiring data and hoping that the 
Ovterrupt can be serviced before the next point is ready. DMA acquisition 
ards simply put the entire array of data points in memory without inter- 
qappting the processor, and then cause a single interrupt when all points have 
veen acquired. 


}@@e@ 
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The DMA controller consists of a number of channels or arbitral 
levels 
ABIOS functions are called through the DevHelp interface and ate 
extremely simple to use. Each DMA device must have a logical ID or LI) 
to communicate with ABIOS. This is obtained with the GetLIDEntry cal) 
Then, all calls to ABIOS are made using the ABIOSCall function with the ¢* 
register pointing to an ABIOS request block. Y 
A great deal of information on call ABIOS routines and on DMA contrw 
is given in the IBM Personal System/2 BIOS Interface Technical Referen_) 
Manual, part number 15F0306. We summarize here the most general», 
useful functions for control of data acquisition hardware. Y 
, 
, 
WV 
This is accomplished by simply loading the registers with the DMA devi_) 
ID and calling the DEVHELP routine 


Getting a Logical ID 


&) 
/* get logical ID for communicating with ABIOS */ &) 
reg n.al = DMA Device I'D; 
reg.h.bl = 0; /*get first unclaimed LID*AY 
reg.h.dh = 1; /*DMA is a shared device ‘“ 
reg.h.dl = DevHIp GetLIDEntry; /*function code ae 
reg.x.es = 0; /*‘must be 0 to avoid tS 
/*“protection exceptions “@ 
YW 


err = CDevHelp(preg); 


where DMADevice_ID has the value Oxf indicating that the device afl 
DMA device. The remaining values of this argument are for internal devidws 
such as keyboard, clock, video, etc., and are listed in the BIOS technical ry 
erence manual. None of the remaining values are useful in writing dev@® 
drivers for laboratory data acquisition cards. © 


J 
For a DMA device to work, you must allocate physical memory and pass t_) 
address of that block to ABIOS, using the AllocPhys DevHelp call 


Allocating Physical Memory 


660 e<¢ 
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G.X.ax = 

HIUSHORT(bufsize);  /*get high part of 32-bit size*/ 
Gh. = 

LOUSHORT(bufsize); /*get low part of 32-bit size*/ 


9000009 


1eg-h.dh = 0; /*“above 1 Mbyte boundary a 
Odg-h.d) = DevHlIp AllocPhys; /*function code at | 
@eg.x.es = 0; /*required * / 
O- = CDevHelp(preg); 

o- | | 
aaysptr . /“ax:bx is 32-bit physical address*/ 


MAKEULONG(reg.x.bx, reg.x.ax); 


hile this DevHelp call will return a pointer to any size memory block, the 
OMA controller is limited to handling blocks of 64K words or 128K bytes at 
ime. 
If you want this data block to be accessible by the user program while it 
is being filled with data by the DMA controller and ADC card, you need to 
vert the physical address to a user virtual address as we did before: 


ao _ ; 
reg.x.ax = HIUSHORT(physptr); /“high part of address “/ 

O)reg.x.bx = LOUSHORT(physptr); /*low part #Y 

g@areg.X%.cx = bufsize; /*size of buffer oF 
reg.h.dh = 1; /*readable and writeable*/ 

Oreg.h.dl = DevHIp AllocPhys; /*function code oF 

Myreg-x-es = 0; /*required * / 

6... = CDevHelp(preg); 

~ Mypreg->GioData = 
o- MAKEP(reg.x.es, reg.x.bx); /*return address = J 


los 


Making Calls to ABIOS 


IOS calls are made using the DevHelp call with SI pointing to the 
CS8IOS request block, which has the form 


“ 
a 
a 
o 
r% 
a 
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struct abios request 


beeceec 


begin 
int blocklen, /*length of request block ’ Jo 
logid, /*logical ID 
unit, /*unit number © 
function, /*“input functio number */@ 
resl, p Seeerace @ 
res2, /*“reserved / 
retcode, /*return code lad 
timeout; /*time out in seconds x 16% “@ 
/*call-specific parameters for DMA calls a 
/* start at offset 0x10 * IS 
int res3; /*reserved af 
long dataptr1, /*‘pointer to input data  “*/ 
resh, /*reserved 4 bytes a 
dataptr2, /*2nd pointer to input “/@ 
params; /*whatever follows to end */ 
end; Y 


Some of the most common ABIOS calls you might use are listed below. The 
left column is the function code. The indented values are the call-specifte’ 


offsets into the ABIOS request packet. 


0x3 Read DMA parameters. 


0x10 word 
0x12 word 
0x14 byte 
0x15 byte 


Oxb Allocate arbi 
Oxl1f byte 


maximum address under 1MB 
maximum DMA transfer size 
number of arbitration levels 
number of DMA channels 


tration level 


arbitration level to allocate 


Oxc Deallocate arbitration level 


Ox1f byte 


arbitration level to deallocate 


Oxe Get DMA transfer count 


Ox1f byte 
0x18 long 


arbitration level to check 
number of bytes left to transfer 


SSOOOOHOOOOCCOOCSE SE 
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AALS, 


f Abort transfer 


* Oxlf byte arbitration level to abort 
om 0x18 long number of bytes not transferred 
OrxW10 ReadMemoryWritelO 
“oy 0x10 long physical address of memory 
| 0x14 long physical address of I/O 
a 0x18 long number of bytes to transfer 
: Oxlc Mode control 
oO bits 7-3. reserved 
on bit 2 programmable I/O 
a bit 1 reserved 
on bit 0 auto initialization 
bd Oxld transfer control | 
Oo bit 2 O=increment, 1=decrement 
am bit 0 device size 0=8 bit, 1=16 bit 
PD Oxle transfer control 2 
| bit O device size 0=8 bit, 1=16 bit 
o 
all ReadIOWriteMemory- Same offsets as 0x10 
oO 


-atructures for ABIOS Calls 


nce the arguments from offset 0x10 up vary with the call, it is often useful 
@ set up some equivalent structures that are then overlaid as UNIONs with 
Aahe base abios_request structure 


gairuct abios DMA 10 


begin 

int blocklen, /*length of request block */ 
logid, /*logical ID i 
unit, /*unit number “7 
function, /*input functio number a 
resl, /*reserved a 
res2, /*reserved wy 
retcode, /*return code i 


»9909000000 
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/*call-specific parameters for 


wl 
J nw 


timeout; 


Start at offset 0x10 
long memoryadd, 
lOaddr, 
count; 
char mode, 
controll, 
controlz, 
arblevel; 
end; 
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WY 
Ww 


/*time out in seconds x 16%*/ 


DMA calls 


/*“physical memory address 
/*physical 1/0 address 


/*words to transfer 
/*mode control 


/*count and device size 


/*device size 2 
/*arbitration level 


Setting up the Arbitration Level 


* / VW 
* A 


*(@ 

* / 

mA 4 

rx / 

KNW 

“© 
WW 
wy 


/ 


Each board is set up in a PS/2 using the installation diskette, and its arb 
tration level can be selected at that time. Before using this level, you mu_) 


tell ABIOS to allocate it using the AllocArbLevel ABIOS function. 


struct abios DMA _10 ab; 


ab. 
ab. 
ab. 
ab. 
ab. 
ab. 
ab. 
ab. 


blocklen = sizeof(abios request); /*set packet size 
/*set logical id 


logid = LID; 

unit = 0; 

function = Oxb; 
retcode = Oxffff; 
timeout = 0; 

resl = QO; 

arblevel = arblevel; 


reg.x.ax = Lips 


rég.X.Sl 


reg.h.dh = 0; 


reg.nh.dl 


AB10Scall; 


reg.x.es = 0; 


err = CDevHelp(preg); 


LOUSHORT(ab) ; 


/*unit=0 


/*allocate arb level” 
/*“must initialize 
/*infinite wait 


/*from POS on board * 
/*set logical ID 


/“offset of packet 
/*selected is in DS 


/“entry point 


/*call function # 
/*must be zero 


/*make call 


sh 


s6 


OOOSOD OE 


sh 


4, 


s sa Sh Sh 4 
a g C t r¢ “v ‘a rE 


XT 


Ait. 
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Setting up the DMA Transfer 


fo initiate a transfer, you must set the DMA count to one less than the 
.ctual number of words or byte to transfer, because the DMA controller ter- 
yinates when the count changes from 0 to -1. You need to indicate the phys- 
cal memory address to transfer to and the I/O port address on the board to 


gq ester tron! 
gab.blocklen = sizeof(abios DMA 10); /*set block size mel 
ab. logid = LID; /*logical 10 oF 
Ob.unit = 0; /*no units involved ef 
onp.function = 0x11; /*read 10 write memory */ 
ab.retcode = Oxffff; /“initialize */ 
Ob.timeout = 0; /*no timeout ay 
mb.count = buffercount -1; /*set to count -1 *Y 
ge -memoryadd = physptr; /“physical memory add “*/ 
“ub. 10addr = Board!|OPort; /*“your board's 10 port */ 
p.arblevel = arblevel; /*your board's arb level*/ 
cab .mode = 0x4; /*programmed lO, no init*/ 
~b.controll = 0x1; /*increment- word size “*/ 
».control2 = 0x1; /*word size a 
2) ' ! 
1reg.x.ax = LID; /*set logical id a 
2g.x.Si = LOUSHORT(ab) ; /“offset to request blk */ 
meg. h.dh = 0; /*entry point a 
reg.h.dl = ABIOSCal1; /*function number a 
bg.x.es = 0 /*must be 0 tf 
oy 
ar = CDevHelp(preg); /*call DevHelp xy 


, Under current versions of OS/2, the DMA controller does not set the board 
O port address, so you must also do this directly with calls to outp. 


© outp(oxi8, Ox7); /*DMA controller 1/0 address */ 
™) outp(0xla, 
LOBYTE(Board|0Port); 
outp(Oxla, 


HIBYTE(Board!0Port); /*high byte of Board |/0 port*/ 


/*low byte of Board 1/0 port */ 


IO 


SA. 
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Deallocating the Arbitration Level 


eooes 


Once your device driver completes data acquisition, you should deallocatw | 
the arbitration level you are using. This is done exact as shown above fo.) 
allocating it, except for the function number in the call: 


struct abios DMA 10 ab; 
ab.blocklen = sizeof(abios request); 
ab. logid = LID; 

ab.unit = 0; 

ab. function = Oxc; 
ab.retcode = Oxffff; 
ab.timeout = 0; 

ab.res!l = 0; 

ab.arblevel = arblevel; 
rég.X,ax = LID; 

reg.x.si = LOUSHORT(ab); 
req. hadh — G; 

reg.h.d] = ABIOScal1; 
reg. x.6s = 0; 


err 


= CDevHelp(preg); 


/*set logical id 
/*unit=0 


/*deallocate arb level 


/*must initialize 
/*timeout 


/*from POS on board 


/*set logical ID 
/*“offset of packet 
/*selected is in DS 
/*“entry point 
/*call function # 
/*must be zero 


/*make call 


Uo 
LU 


a ” Ae i 
/*set packet size™/— 


* /& 
* / | 
* a4 
«1S | 


/@ 
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_«BIOS functions, 384 
celerators, 94 
cumulator registers, 298 
acquiring data points, 320 
ding menu items, 90 
eoddress of arrays, 22 
addressing modes, 305 
' locating physical memory, 384 


~ @achor block, 274, 279 


AND, 17 
\ igle brackets in include files, 27 


| @Mbitration level, 388 


gument string passed from 
| S/2, 281 
%guments to functions, 25 
ithmetic shift, 302 
_.faysinC, 10 


| (SCII characters, 212 
| gacembly language, 4, 297 


29000 


asynchronous paint window, 63 
auto radio button, 102 
automatic response file, 53 
automatic variables, 26 


B 
backslash, 9 
backspace, 10 
base pointer, 300 
base register, 299 
base relative addressing, 307 
based addressing, 307 
based indexed addressing, 308 
baud rate, 211 
setting, 219 
beginthread, 46 
BGA display, 261 
BIOS code, 299 
bit AND, 12 
bit manipulations, 6 


So 1 
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bit operations, 12 
bitOR, 12 
bitmap, 255 

raster operations, 259 
block devices, 325 
blocking, 46 
blocks of statements, 16 
BM_SETCHECK, 107 
BN_clicked, 109 


BOOL, 59 
borders, 57 
BP, 300, 306 
braces, 9, 16 
break, 


exiting from loops, 18 
break statement, 18 


C 


C calling convention, 198 
C compiler, 4 
C language device driver, 353 
C preprocessor, 32 
for help processing, 131 

C readability definitions, 32 
cached micro PS, 68 
CALL instruction, 309 
calling DLL functions, 194 
capitalization in assembly 

language, 300 
carry flag, 303 
case, in switch statement, 17 
casting variables, 24 
cdefs.h, 32,50 
CGA display, 26] 
chained segments, 244 
changing lookup tables, 262 


changing menu items, 88 
changing the pointer shape, 189 
char type, 7 

character constants, 9 
character devices, 325 
characters, 11 

check boxes, 100 
CHGCOLOR program, 111 
child process, 280 

child windows, 155,175,177 
class, window, 61 

class name, 67 

client area, 63 

client window, 65 

clocks, 8PGA, 322 

clocks in acquisition, 320 
close call, 366 

CMP, 304 

code segment, 37, 299 
CodeView, 34, 199 

color lookup table, 257 
COM device driver, 212 
combination operators, 20 
COMM ports, 211 
command dispatch atble, 328 
comments, 8, 31 

compact model, 37 
comparison operators, 16 
compiler switches, 38 
compiling, 49 

compiling a help file, 136 
conditional jump instructions, 30 
CONFIG.SYS, 271, 330 
contiguous segments, 41 


control register, 322 
converting between data types, 2 


CCCCccedeoosé 
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™) correlating segments, 246 
counter register, 299 
‘creating a bitmap, 256 
creating a child window, 177 
creatinga DLL, 192 
“creating and picking segments, 247 
ONCRTLIB library, 192, 198 
CS_CLIPCHILDREN, 157 
‘CX, 311 
ma 


™D 
qmpdata acquisition, 346 
data register, 299 
' datasegment, 37, 299 
6Mdata segment register, 39 
data types, 58 
pcs. 219 
OYDCE ports, 213 
debugging, 34 
debugginga DLL, 199 
(Mdecision-making instructions, 304 
decisions, making inC, 15 
decrement operator, 19 
OFF file, 156 
for DLLs, 195 
LIBRARY statement, 198 
Oefault, in switch, 18 
endefault printer, 202 
define statement, 13 
Jefinition lists, 130 
emMefinitions file, 73 
dependencies, in MAKE, 54 
ODESCRIPTION statement, 53 
OMestination operand, 300 
determining a parent, 178 
YevCloseDC, 241 
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DevEscape, 208 
DevHelp, 361 
device context, 206, 240, 256 
device control block, 
serial, 219 
device driver, 
for printers, 202 
header block, 323 
inc, 353 
parts, 323 
reserving memory, 333 
device drivers, 319 
COM, 212 
device help routine, 330 
device name, 325 
DEVICE= statement, 330 
DevOpenDC, 240 
DEVOPENSTRUC, 203 
Dev_help, 323 
DI, 300, 311 
dialog box, 99, 155, 232 
procedures, 106 
dialog box file, 73 
DID_CANCEL, 105 
DID_OK, 105 
direct addressing, 306 
direct indexed addressing, 307 
display buffer, 275 
DISPLAY.DLL, 240 
dithering, 261 
DLG files, 103 
DLGBOX editor, 101 
DLLs, 73,191 
debugging, 199 
loading, 195 
DMA channels, 383 
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DMA transfer, 389 
do-while loop, 22 
Dos memory allocation 
functions, 41 
DosAllocHuge, 42 
DosAllocSeg, 41, 293 
DosConnectNmPipe, 291 
DosCreateQueue, 294 
DosCreateSem, 46, 284 
DosCreateThread, 47 
DosDelete, 241 
DosDevIOCtrl, 212 
serial devices, 217 
DosExecPgm, 280 
DosExit, 49 
DosFindFirst, 228 
DosFindNext, 228 
DosFreeSeg, 41, 293 
DosGetPID, 293 
DosGetProcAddr, 196 
DosGiveSeg, 293 
DosLoadModule, 196 
DosMakeNmPipe, 290 
DosMakePipe, 288 
DosOpen, 214 
DosPeekQueue, 294 
DosPortAccess, 316 
DosQCurDisk, 237 
DosRead, 217 
DosReadQueue, 294 
DosReallocSeg, 41 
DosSelectDisk, 237 
DosSemClear, 284 
DosSemRequest, 46, 284 
DosSemSet, 46, 284 
DosSemSetWait, 284 


DosSemWait, 284 

DosSleep, 285 

DosWrite, 217 

double clicking on title bar, 71 
double precision, 5, 7 

drawing lines, 170 
DRIVDATA structure, 205 
drive names, 237 

driver initialization, 323 
drop-down menus, 79 
DRO_OUTLINE, 173 

DS, 306 

DTE ports, 213 

DTR input handshaking, 221 
DTR signal, 221 

dual operand instructions, 300 
Dynamic Link Library, 73, 191 
dynamic segments, 245 


E 

edit boxes, 100 

editing segments, 250 
EGA display, 261 
electron microscopy, 255 
elevator in scroll bar, 225 
enabling menu items, 88 
end addresses, 360 

end of interrupt signal, 341 
environment variable, 271 
EOI, 341 

equals sign, 9,17 
Etch-a-Sketch, 167 

even parity, 212 
exception, | 

exclusive OR, 12 


exclusive OR drawing mode, 172 
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™ EXPORTS, 105 
inDLLs, 193 
EXPORTS statement, 74, 156 
M%extra bytes, 157 
extra bytes in window 


> 


structures, 156 


-™ 


far pointers, 38 
far procedures, 310 
/fast-chaining, 244 

a fast-safe RAM semaphores, 283, 


287 
Diclose. 28 
fgets, 28 


aysile handling, 28 
\-FILEFINDBUF structures, 228 
filled box, 174 
flag registers, 303 
floating point, 5,7 
©) JEEEstandard, 7 
fmalloc call, 40 
) fopen, 28 
Yor loops, 20 
em format string for printf, 13 
frame, 63, 72 
frame window, 88 
emframe window identifier, 64 
function calls, 
serial devices, 217 
OMfunction prototypes, 26 
functions, 24 
arguments to, 25 
arrays as arguments, 25 


o 
pes 
o~ 
~ 
~ 
pd 
o 
a 
a 
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GDT, 333, 348, 360 
generic !/O control calls, 364 
GenlOCtrl commands, 343 
global descriptor table, 333 
GpiAssociate, 24] 
GpiBitBlt, 259 

GpiBox, 173 
GpiCallSegmentMatrix, 252 
GpiCloseSegment, 245 
GpiCorrelate, 245 
GpiCorrelateChain, 246 
GpiCorrelateSegment:, 246 
GpiCreateBitmap, 256 
GpiCreateLogColorTable, 261 
GpiDrawChain, 246 
GpiLabel, 247 
GpiOpenSegment, 245 
GpiPlayMetaFile, 242 
GpiPolyLine, 275 
GpiRealizeColorTable, 261 
GpiSaveMetaFile, 241 
GpiSetBitmapBits, 258 
GpiSetEditMode, 251 
GpiSetPickAperture, 249 
GpiSetTag, 247 

graphics orders, 239 
graphics segments, 70, 239, 244 
graphics transforms, 251] 
gullible programs, 34 


halloc call, 40 
handle, 58, 59 
to files, 28 
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handshaking, 221 

hDC, 206 

header program, 369 

header program for device 
driver, 355 

HEAPSIZE, 53 

Hello program, 61 

HELLOJ1 program,, 76 

help, 4 

help hook, 124 

help index, 134 

help instance, 137 

help manager, 127 
types of lists, 129 

help markup, 127 

help panels, linking, 130 

HELPSUBITEM, 133 

HELPTABLE, 133 

hexadecimal notation, 7 

hiding mouse pointer, 175 

hiding the pointer, 178 

histogram, 264 

histogram equalization, 265 

HK_HELP, 124 

HK_JOURNALRECORD, 124 

HMQ, 60 

HM_QUERYKEYS_HELP, 134 

HPS, 59 

HSEM, 60 

huge allocation, 42 

huge data arrays, 41 

huge model, 38 

huge shift, 43 
Hungarian notation, 47 
HWND, 59 


HWND_DESKTOP, 64, 106 


hypertext, 127 
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IBM C/2, 6 
icon, 80 
icon file, 67, 73 


ICONEDIT program, 93 
IEEE floating point, 7 

if statement, 15 

image, 255 

immediate addressing, 306 
IMPLIB program, 199 
IMPORTS statement, 195 


INCLUDE, 
environment variable, 271 
include files, 27, 72 


include statement, 9 
increment operator, 19 
indentation, 15 
index registers, 300 


indexed indirect addressing, 307 


INIT command, 331 
initialization, 172 

82, 171 
initialization routine, 359 
314, 362 
input serialization, 270 


of windows, 
inp function, 


instances of windows, 156 
instructions and data, 298 
integer type, 7 

intensity histogram, 264 
interpreting menu commands, 
interrupt, registering, 337 
interrupt handler, 338 
interrupt service routine, 323 


interrupts, 3, 320 
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invalidating rectangles, 82 
a IOPL, 35 
IOPL segment, 316 
©) IOPL segment program, 314 
IPFC compiler, 127 
I/O privileges, 313 


) key codes, 96 
keyboard codes, 96 
keyboard messages, 270 
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a» large model, 38 
LDT, 333 


‘left shift, 12 
em LIBPATH variable, 191 
library functions, 29 
LIBRARY statement, 198 
©» line characteristics, serial, 219 
line drawing, 170 
~_/ Link file, 76 
™) linking, 52 
linking help panels, 130 
list boxes, 100, 225 
) LLIBCDLL library, 192 
wa LLIBCMT, 270 
LM_QUERYSELECTION, 227 
Mloadinga DLL, 195 
local descriptor table, 333 
logical AND, 17 
Ological NOT, 17 
™y logical OR, 17 
logical shift, 302 
_/long integer type, 7 
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loop instructions, 304 
looping statements, 20 
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macros, 32 
MAKE file, 72, 75 
MAKE program, 54 

versions, 55 
making decisions inC, 15 
malloc call, 40 
malloc function, 23 
mark parity, 212 
markup language, 127 
math coprocessor in DLLs, 192 
MATRIXLF structure, 252 
medium model, 37 
memory, in device drivers, 333 
memory allocation, 23, 347 
memory device context, 256 
memory models, 37, 323 
memory segments, sharing, 292 
memory suballocation, 43 
menu accelerators, 94 
menu bars, 57 
MENU directive, 80 
menu items, 

adding, 90 

changing, 88 

underscored, 94 
menu separators, 81 
menus, 66, 79 
message queue, 62, 269, 279 
message queues, 295 


messages, 
user-defined, 176 
metafile, 239 


playing back, 242 
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MIA_CHECKED, 89 
MIA_DISABLED, 89 

micro presentation space, 68, 172 
microprocessor types, 298 
microscopy, 255 

Microsoft C, 6 

minimize box, 71 
MLEFIE_CFTEXT, 122 
MLFIE_NOTRANS, 122 
MLM_EXPORT, 123 
MM_INSERTITEM, 90 
MM_SETITEMATTR, 88 
modulo, 12 

mouse, 167 

mouse buttons, 60 

mouse messages, 270 

mouse pointer, 175 

mouse pointer visibility, 174 
moving objects withe mouse, 172 
MPARAM, 59 

MRESULT, 59 

multi-thread library, 76 
multi-thread program, 45 
multiline edit box, 100, 122 
multiple register load 
instructions, 311 
multitasking, 2, 269 
multithread, 52 

multithread include files, 27,52 
multithread library, 270 
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NAME statement, 53 

named memory segments, 293 
named pipes, 290 

near pointes, 38 


near procedures, 310 

new line character, 10 
nmalloc call, 40 

NMR, 255 

non-printing characters, 10 
normal PS, 68 

NOT, 17 

nuclear magnetic resonance, 
NULL byte in strings, 10 
null parity, 212 
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object modules, 6 

octal notation, 7 

odd parity, 212 

offset register, 37 

one’s complement, 12, 17 
OPEN command, 335 
OR, 17 

OS2.INI profile, 202 
OS/2 data types, 58 
OS/2 structures, 59 
outp function, 314, 362 
overflow flag, 303 


ownership of semaphores, 284 
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packed structures, 257 
packet status byte, 327 
paint message, 57 
paint routine, 70 


parent, 178 
parity bit, 212 
PASCAL, 59 


Pascal calling convention, 
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as Pascal style function calls, 51 
physical address, 385 
physical addresses, 333 

™) pick aperture, 249 
picking segments, 246 

‘ )PICPRINT, 239 

™) pin assignments, 

RS-232, 212 

“ 8PGA, 321 

pipes, 283, 288 
pixel, 255 
playing back a metafile, 242 

YPLOTTERS.DRYV file, 204 

@ Pointer, hiding, 178 

- pointer shape, 189 
©) pointers, 
Pou’ incrementing, 23, 24 
Strings as, 23 

oy to structures, 30 

| m types, 24 
pointers inC, 22 

_ pointers in device driver, 354 

AMPOINTL, 59 
POINTL structure, 157 
polyline drawing, 275 

ports, serial, 211 

a FOS, 332 
posting messages, 177 

preprocessor, inC, 32 

presentation space, 206, 240, 256 
presentation spaces, 68 

print manager program, 201 

printer names, 202 
printf, 9 

printf statement, 13 

omprinting ascreen, 203 
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process, 

child, 280 
processes, 2 
program gullibility, 34 
programmable option select, 332 
Programmeréaps.s Toolkit, 4 
protected mode, 1, 298, 299, 341] 
protected modes, 313 
protection rings, 3, 313 
PROTMODE statement, 316 
prototypes, of functions, 26 
PS, 68, 206 
push buttons, 99,101, 102 
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queue processor, 201 
queues, 283, 294 
Quick-C, 6 

quoted include files, 27 
QW_BOTTOM, 178 
QW_NEXT, 178 
QW_PREV, 178 
QW_TOP, 178 
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radio buttons, 99, 100 
auto, 102 
RAM semaphores, 45, 283, 286 
raster operations, 259 
RC file, 79 
re-entrant functions, 52 
real mode, 1, 313, 341 
realizing a lookup table, 261 
RECTL, 59 
RECTL structure, 125 
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register addressing, 306 
registering a help instance, 137 
registering a window class, 61 
registering an interrupt, 337 
repainting a window, 57, 82 
REPxx, 311 
RES files, 73, 103 
reserving memory, 333 
resizing a window, 57 
resource compiler, 94, 198 
resource file, 73, 75,79 
RESULTCODES structure, 281 
RET instruction, 309 
right shift, 12 
rings, 313 
rings of protection, 3 
rotate instructions, 302 
RS-232, 

pin assignments, 212 
RS-232 standard, 211 
RTS signal, 221 


S 


SB_LINEDOWN, 118 
SB_LINEUP, 118 
SB_PAGEUP, 118 
SB_SLIDERPOSITION, 118 
scan codes, 96 
scanf function, 27 
scanning tunnelling 

microscopy, 255 
scroll bar, 

elevator, 225 
scroll bars, 100,118 
SC_HELPEXTENDED, 132 
segment address, 299 


segment register, 37 
segment registers, 299 
segment setup, 39 
segment transform matrix, 245 
segments, 

correlating, 246 

editing, 250 

labels, 247 

tags, 247 
segments, graphics, 239 
segments, memory, 37 
SEGMENTS statement, 316 
SEM, 255 
semaphore, 45, 349 
semaphore ownership, 284, 286 
semaphore sharing, 285 
semaphores, 2, 283 

purposes of various types, 288 
semicolon, 9 
sending messages, 177 
separators, 81 
serial device function calls, 217 
serial ports, 211 
serialization of input, 270 
SetDCBInfo, 221 
SetIRQ call, 337 
shared interrupts, 341 
sharing memory segments, 292 
sharing semaphores, 285 
shift, 

huge, 43 
shift instructions, 302 
SHORT2FROMMP macro, 83 
showing mouse pointer, 175 
SI, 300, 311 
sign flag, 303 
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signed comparisons, 304 
| single operand instructions, 301 
small model, 37 
©) small model C, 353 
SMSW instruction, 341 
3 source operand, 300 
™ SP, 300 
spool file, 201 
sprintf function, 15 
) SS, 306 
sscanf function, 27 
stack, 308 
© stack pointer, 300 
a STACKSIZE, 53 
standard window, 63 
oy Static variables, 26 
™» Status register, 320 
STM, 255 
@ strategy routine, 323, 326, 357 
_ @™)\String instructions, 310 
‘string tables, 116 
strings, 10, 11 
) copying, 11 
strings as pointers, 23 
‘structured programming, 33 
structured programs, 5 
structures, 59 
structures in C, 29 
(STUB statement, 53 
style bit, 157 
suballocation of memory, 43 
Msubclassing window 
procedures, 184 
subdirectory, 232 
_( %ubdirectory names, 229 
SUBMENU directive, 80 
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switch statement, 17, 61 
switches, compiler, 38 
synchronous-paint window, 63 
system menu, 71 

system semaphore, 46 

system semaphores, 283 
system timer functions, 45 


T 


tab character, 10 
task list, 64 
tasks in child windows, 157 
terminating a window program, 67 
ternary operator, 19 
TEST, 304 
text boxes, 100, 116 
threads, 2,269 
anchor block in, 274 
creating, 46 
threads and message queues, 295 
tile bar, 71 
timer thread, 45 
timers, 156 
transform matrix, 245 
transforms, graphics, 251 
trap D, 40 
TSR programs, 3 
Turbo C, 6 
two dimensional arrays, 11 
typedef, 30 
types of lists in help, 129 


UCHAR, 59 
unnamed pipes, 288 
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user virtual address, 348, 385 
user-defined messages, 176 


Vv 


variable names, 11 

VGA display, 261 

virtual addresses, 333 

virtual keys, 95, 98 

visibility of mouse pointer, 174 
VOID, 59 


Ww 


while loops, 21 
WinAssociateHelpInstance, 137 
WinBeginPaint, 68, 168 
WinCreateHelpInstance, 137 
WinCreateMenu, 90 
WinCreateStdWindow, 61, 62, 
158 
WinCreateWindow, 177 
WinDefWindowProc, 184 
WinDestroyWindow, 160 
WinDispatchMsg, 61, 67 
WinDlgBox, 105, 107, 232 
window, 206 

in second thread, 278 
window class, 61, 62 
window extra bytes, 156 
window handle, 58 
window initialization, 171 
window instances, 156 
window message, 58 
window procedure, 57, 68 
windows in threads, 27] 
WinEndPaint, 68, 70, 168 


WinGetPS, 160 
WinInvalidateRect, 82 
WinLoadAccelTable, 96 
WinLoadString, 116 
WinMessageBox, 116 
WinPostMsg, 177 
WinQueryPointerPos, 188 
WinQueryProfileString, 202 
WinQuerySysPointer, 189 
WinQuerySysValue, 248 
WinQueryWindow, 88 
WinQueryWindowRect, 177, 188, 
240 

WinRegisterClass, 61, 62, 157 
WinReleasePS, 169 
WinSendDlgItemMsg, 108, 225 
WinSendMessage, 89 
WinSendMsg, 177 
WinSetCapture, 174 
WinSetPointer, 190 
WinSetPointerPos, 168 
WinSetWindowULong, 158 
WinShowPointer, 175, 190 
WinStartTimer, 158 
WinSubclassWindow, 187 
WinWindowFromID, 88, 225 
WM_BUTTONIDBLCLK, 167 
WM_BUTTONIDOWN, | 167, 
171, 249 J 
WM_CHAR, 83, 96 
WM_COMMAND, | 80, 226 Y 
WM_CONTROL, | 109, 227 Ly 
WM_CREATE, 83, 158, 184, 187 
WM_DESTROY, 169 
WM_ERASEBACKGROUND, \2 
WM_HELP, 125 
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WM_HSCROLL, 118 
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©) WM_MOUSEMOVE, 167, 171, 
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WM_PAINT, 168 

©) WM_QUIT, 83 

 @) WM_TIMER, 157 
WM_USER, 176 

| WM_VSCROLL, 118 

_ @) writing toa queue, 294 


aN 
ae 


XON-XOFF handshaking, 222 
©) xor drawing mode, 172 
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“Zp compiler option, 257 
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